文章作者:Tyan
博客:noahsnail.com | CSDN | 简书
Part I. Spring Boot Documentation
This section provides a brief overview of Spring Boot reference documentation. Think of it as map for the rest of the document. You can read this reference guide in a linear fashion, or you can skip sections if something doesn’t interest you.
这部分是Spring Boot参考文档的概述。可以将它作为文档其它部分的地图。你可以依次阅读参考手册,或者直接跳过你不感兴趣的章节。
1. About the documentation
The Spring Boot reference guide is available as html, pdf and epub documents. The latest copy is available at docs.spring.io/spring-boot/docs/current/reference.
Sring参考文档可以通过html,pdf和epub 三种形式得到。最新的文档可以从docs.spring.io/spring-boot/docs/current/reference上得到。
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
本文档的副本无论是电子版还是打印版,只要你不收取任何费用且在每个副本中包含了版权声明,你就可以自由使用本文档的副本或分发给其它人。
2. Getting help
Having trouble with Spring Boot, We’d like to help!
Try the How-to’s — they provide solutions to the most common questions.
Learn the Spring basics — Spring Boot builds on many other Spring projects, check the spring.io web-site for a wealth of reference documentation. If you are just starting out with Spring, try one of the guides.
Ask a question - we monitor stackoverflow.com for questions tagged with spring-boot.
Report bugs with Spring Boot at github.com/spring-projects/spring-boot/issues.
如果在使用Spring Boot中有不会的地方,我们很乐意帮忙!
尝试How-to’s(文档第九部分),里面有最常见问题的解决方案。
学习Spring基础知识——Spring Boot建立在许多其它的Spring工程之上,查看spring.io网站,上面有大量的参考文档。如果你刚开始使用Spring,尝试看这些指南中的一个。
问问题——我们监控着stackoverflow.com中标签为
spring-boot
的问题。报告Spring Boot中的bugs请到github.com/spring-projects/spring-boot/issues。
All of Spring Boot is open source, including the documentation! If you find problems with the docs; or if you just want to improve them, please get involved.
Spring Boot是开源的,包括文档!如果你在文档中发现了问题;或你想改进它们,请参与进去。
3. First steps
If you’re just getting started with Spring Boot, or ‘Spring’ in general, this is the place to start!
From scratch: Overview | Requirements | Installation
Tutorial: Part 1 | Part 2
Running your example: Part 1 | Part 2
如果你准备开始学习Spring Boot或通常来说的Spring,从这里开始!
从零开始: 概述 | 要求 | 安装
学习指南: 第一部分 | 第二部分
运行例子: 第一部分 | 第二部分
4. Working with Spring Boot
Ready to actually start using Spring Boot? We’ve got you covered.
Build systems: Maven | Gradle | Ant | Starters
Best practices: Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
Running your code: IDE | Packaged | Maven | Gradle
Packaging your app: Production jars
Spring Boot CLI: Using the CLI
准备好开始使用Spring Boot了?不用担心。
构建系统:Maven | Gradle | Ant | Starters
最佳实践:Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
运行代码:IDE | Packaged | Maven | Gradle
打包应用:Production jars
Spring Boot命令行:Using the CLI
5. Learning about Spring Boot features
Need more details about Spring Boot’s core features? This is for you!
Core Features: SpringApplication | External Configuration | Profiles | Logging
Web Applications: MVC | Embedded Containers
Working with data: SQL | NO-SQL
Messaging: Overview | JMS
Testing: Overview | Boot Applications | Utils
Extending: Auto-configuration | @Conditions
需要更多关于Spring Boot核心特性的细节?看下面。
核心特性:SpringApplication | External Configuration | Profiles | Logging
Web应用:MVC | Embedded Containers
消息:Overview | JMS
测试:Overview | Boot Applications | Utils
扩展:Auto-configuration | @Conditions
6. Moving to production
When you’re ready to push your Spring Boot application to production, we’ve got some tricks that you might like!
Management endpoints: Overview | Customization
Connection options: HTTP | JMX | SSH
Monitoring: Metrics | Auditing | Tracing | Process
当你准备将你的Spring Boot应用变成产品时,给你推荐一些你可能喜欢的小技巧。
管理端点:Overview | Customization
链接选择:HTTP | JMX | SSH
监控:Metrics | Auditing | Tracing | Process
7. Advanced topics
Lastly, we have a few topics for the more advanced user.
Deploy Spring Boot Applications: Cloud Deployment | OS Service
Build tool plugins: Maven | Gradle
Appendix: Application Properties | Auto-configuration classes | Executable Jars
最后,我们有一些课题给高级用户。
部署Spring Boot应用:Cloud Deployment | OS Service
构建工具插件:Maven | Gradle
附录:Application Properties | Auto-configuration classes | Executable Jars
Part II. Getting started
If you’re just getting started with Spring Boot, or ‘Spring’ in general, this is the section for you! Here we answer the basic “what?”, “how?” and “why?” questions. You’ll find a gentle introduction to Spring Boot along with installation instructions. We’ll then build our first Spring Boot application, discussing some core principles as we go.
如果你刚开始学习Spring Boot或通常所说的Spring,这部分就是为你准备的!这部分中我们回答了基本的”what?”,”how”,”why?”问题,并在安装说明中介绍Spring Boot。我们将构建第一个Spring Boot应用,讨论一些我们遵循的核心原则。
8. Introducing Spring Boot
Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can “just run”. We take an opinionated view of the Spring platform and third-party libraries so you can get started with minimum fuss. Most Spring Boot applications need very little Spring configuration.
Spring Boot 使创建独立的、产品级的、基于Spring的应用变得更容易,你只需要运行run
即可。我们采用不变的Spring平台和第三方库,因此你可以几乎无差别的使用Spring Boot。大多数Spring Boot应用只需要很少的Spring配置。
You can use Spring Boot to create Java applications that can be started using java-jar
or more traditional war deployments. We also provide a command line tool that runs “spring scripts”.
你可以使用Spring Boot创建Java应用,用java-jar
或更传统的war包来部署应用。我们也提供了运行”Spring脚本”的命令行工具。
Our primary goals are:
Provide a radically faster and accessible getting started experience for all Spring development.
Be opinionated out of the box, but get out of the way quickly as requirements start to diverge from the defaults.
Provide a range of non-functional features that are common to large classes of projects (e.g. embedded servers, security, metrics, health checks, externalized configuration).
Absolutely no code generation and no requirement for XML configuration.
我们的主要目标是:
为所有Spring开发者提供一个从根本上更迅速可用的入门经验。
坚持开箱即用,当默认设置不满足需求时可以快速避免默认设置。
为具有许多类的工程提供一系列常用的非功能特性(例如嵌入式服务器、安全、度量、健康检查、外部配置)。
绝对没有XML配置代码产生和XML配置需求。
9. System Requirements
默认情况下,Spring Boot 2.0.0.BUILD-SNAPSHOT需要Java 7和Spring Framework 5.0.0.BUILD-SNAPSHOT及以上。你可以通过一些额外配置在Java 6下使用Spring Boot。更多细节请看80.11小节,”怎样使用Java 6”。明确的构建支持有Maven (3.2+)和Gradle (1.12 or 2.x),不支持Gradle 3。
虽然你可以在Java 6或Java 7下使用Spring Boot,但我们建议尽可能的使用Java 8。
9.1 Servlet containers
The following embedded servlet containers are supported out of the box:
Name | Servlet Version | Java Version |
---|---|---|
Tomcat 8 | 3.1 | Java 7+ |
Tomcat 7 | 3.0 | Java 6+ |
Jetty 9.3 | 3.1 | Java 8+ |
Jetty 9.2 | 3.1 | Java 7+ |
Jetty 8 | 3.0 | Java 6+ |
Undertow 1.3 | 3.1 | Java 7+ |
You can also deploy Spring Boot applications to any Servlet 3.0+ compatible container.
下面的嵌入式servlet
容器支持开箱即用:
Name | Servlet Version | Java Version |
---|---|---|
Tomcat 8 | 3.1 | Java 7+ |
Tomcat 7 | 3.0 | Java 6+ |
Jetty 9.3 | 3.1 | Java 8+ |
Jetty 9.2 | 3.1 | Java 7+ |
Jetty 8 | 3.0 | Java 6+ |
Undertow 1.3 | 3.1 | Java 7+ |
你也可以部署Spring Boot应用到任何兼容Servlet 3.0+的容器。
10. Installing Spring Boot
Spring Boot can be used with “classic” Java development tools or installed as a command line tool. Regardless, you will need Java SDK v1.6 or higher. You should check your current Java installation before you begin:
Spring Boot可以和”经典”的Java开发工具一起使用,也可作为一个命令行工具来进行安装。不管你是需要Java SDK v.16还是更高版本,在开始之前你应该检查你当前安装的Java版本。
1 | $ java -version |
If you are new to Java development, or if you just want to experiment with Spring Boot you might want to try the Spring Boot CLI first, otherwise, read on for “classic” installation instructions.
如果你是Java开发的新手,或你只想尝试Spring Boot,你可能首先想试一下Spring Boot CLI,否则,请读”经典”的安装说明。
Although Spring Boot is compatible with Java 1.6, if possible, you should consider using the latest version of Java.
虽然Spring Boot兼容Java 1.6,但可能的话,你应该考虑使用Java的最新版本。
10.1 Installation instructions for the Java developer
You can use Spring Boot in the same way as any standard Java library. Simply include the appropriate spring-boot-*.jar
files on your classpath. Spring Boot does not require any special tools integration, so you can use any IDE or text editor; and there is nothing special about a Spring Boot application, so you can run and debug as you would any other Java program.
你可以使用Spring Boot像使用任何标准Java库一样。简单的在你的classpath
中包含恰当spring-boot-*.jar
即可。Spring Boot不需要任何特定的工具集成,因此你可以使用任何IDE或文本编辑器;Spring Boot应用没有什么特别的,你可以像其它的Java程序一样来运行和调试。
Although you could just copy Spring Boot jars, we generally recommend that you use a build tool that supports dependency management (such as Maven or Gradle).
尽管你可以只拷贝Spring Boot的jars,但通常我们建议你使用一个支持依赖管理的构建工具(例如Maven或Gradle)。
10.1.1 Maven installation
Spring Boot is compatible with Apache Maven 3.2 or above. If you don’t already have Maven installed you can follow the instructions at maven.apache.org.
Spring Boot兼容Apache Maven 3.2或以上。如果你没有安装Maven,你可以根据maven.apache.org的说明来安装。
On many operating systems Maven can be installed via a package manager. If you’re an OSX Homebrew user try
brew install maven
. Ubuntu users can runsudo apt-get install maven
.
在许多操作系统上Maven都能通过包管理器来安装。如果你是一个OSX Homebrew用户可以通过
brew install maven
安装。Ubuntu用户可以通过sudo apt-get install maven
安装。
Spring Boot dependencies use the org.springframework.boot
groupId
. Typically your Maven POM file will inherit from the spring-boot-starter-parent
project and declare dependencies to one or more “Starters”. Spring Boot also provides an optional Maven plugin to create executable jars.
Spring Boot依赖使用org.springframework.boot
groupId
。通常你的Maven POM文件将继承spring-boot-starter-parent
工程并声明一个或多个“Starters”依赖。Spring Boot也提供一个可选的Maven插件来创建可执行的jar包。
Here is a typical pom.xml
file:
下面是一个典型的pom.xml
文件:
1 | <?xml version="1.0" encoding="UTF-8"?> |
The
spring-boot-starter-parent
is a great way to use Spring Boot, but it might not be suitable all of the time. Sometimes you may need to inherit from a different parent POM, or you might just not like our default settings. See Section 13.2.2, “Using Spring Boot without the parent POM” for an alternative solution that uses animport
scope.
spring-boot-starter-parent
是使用Spring Boot的一种极好的方式,但它可能不是一直都合适的。有时你可能需要继承一个不同的父POM,或者你可能不喜欢我们的默认设置。请看13.2.2小节,『没有父POM的情况下使用Spring Boot』是一种可替代的解决方案,它使用了import
作用域。
10.1.2 Gradle installation
Spring Boot is compatible with Gradle 1.12 or 2.x. 2.14.1 is recommended. Gradle 3 is not supported. If you don’t already have Gradle installed you can follow the instructions at www.gradle.org/.
Spring Boot兼容Gradle 1.12或2.x。推荐使用2.14.1。不支持Gradle 3。如果你没有安装Gradle,你可以根据www.gradle.org/的介绍来安装。
Spring Boot dependencies can be declared using the org.springframework.boot group
. Typically your project will declare dependencies to one or more “Starters”. Spring Boot provides a useful Gradle plugin that can be used to simplify dependency declarations and to create executable jars.
Spring Boot依赖使用org.springframework.boot
groupId
。通常你的工程会声明一个或多个“Starters”依赖。Spring Boot提供了一个有用的Gradle插件用来简化依赖声明并创建可执行的jar包。
Gradle Wrapper
The Gradle Wrapper provides a nice way of “obtaining” Gradle when you need to build a project. It’s a small script and library that you commit alongside your code to bootstrap the build process. See https://docs.gradle.org/2.14.1/userguide/gradle_wrapper.html for details.
Gradle Wrapper
当你需要构建一个工程时,Gradle Wrapper提供了一种很好的方式来『获得』Gradle。它是一小段脚本和库,并随着你的代码一起提交来引导构建过程。更多细节请看https://docs.gradle.org/2.14.1/userguide/gradle_wrapper.html。
Here is a typical build.gradle
file:
下面是一个典型的build.gradle
文件:
1 | buildscript { |
10.2 Installing the Spring Boot CLI
The Spring Boot CLI is a command line tool that can be used if you want to quickly prototype with Spring. It allows you to run Groovy scripts, which means that you have a familiar Java-like syntax, without so much boilerplate code.
Spring Boot CLI是一个命令行工具,可以用来快速搭建基于Spring的原型。它允许你运行Groovy脚本,这意味着你有一个熟悉的类Java语法,没有很多的样本代码。
You don’t need to use the CLI to work with Spring Boot but it’s definitely the quickest way to get a Spring application off the ground.
你不需要使用CLI来使用Spring Boot但它是开始得到一个基于Spring应用的最快方式。
10.2.1 Manual installation
You can download the Spring CLI distribution from the Spring software repository:
你可以从Spring软件仓库下载Spring CLI发行版:
Cutting edge snapshot distributions are also available.
最新的snapshot distributions也是可获得的。
Once downloaded, follow the INSTALL.txt instructions from the unpacked archive. In summary: there is a spring
script (spring.bat
for Windows) in a bin/
directory in the .zip
file, or alternatively you can use java -jar
with the .jar
file (the script helps you to be sure that the classpath is set correctly).
一旦下载完成,按照存档INSTALL.txt中的 介绍来安装。总结:bin/
目录的.zip
文件中有一个spring
脚本(Windows中是spring.bat
),或者你可以使用java -jar
运行.jar
文件(这个脚本帮你确保正确设置classpath)。
10.2.2 Installation with SDKMAN!
SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions of various binary SDKs, including Groovy and the Spring Boot CLI. Get SDKMAN! from sdkman.io and install Spring Boot with:
SDKMAN! (The Software Development Kit Manager)能用来管理各种二进制SDKs的多个版本,包括Groovy和Spring Boot CLI。从sdkman.io中得到SDKMAN!并安装Spring Boot:
1 | $ sdk install springboot |
If you are developing features for the CLI and want easy access to the version you just built, follow these extra instructions.
如果你在为CLI开发功能并向很容易的访问你够简单版本,按照这些额外的介绍去做。
1 | $ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.0.0.BUILD-SNAPSHOT-bin/spring-2.0.0.BUILD-SNAPSHOT/ |
This will install a local instance of spring
called the dev
instance. It points at your target build location, so every time you rebuild Spring Boot, spring
will be up-to-date.
这将会安装一个名为dev
的本地spring
实例。它指向你的目标构建位置,因此你每次重新构建Spring Boot,spring
将是最新的。
You can see it by doing this:
按下面去做你会看到:
1 | $ sdk ls springboot |
10.2.3 OSX Homebrew installation
If you are on a Mac and using Homebrew, all you need to do to install the Spring Boot CLI is:
如果你在Mac上使用Homebrew,安装Spring Boot CLI所有你需要做的是:
1 | $ brew tap pivotal/tap |
Homebrew will install spring
to /usr/local/bin
.
Homebrew会在/usr/local/bin
目录安装spring
。
If you don’t see the formula, your installation of brew might be out-of-date. Just execute
brew update
and try again.
如果你没有看到公式,你安装的brew可能过时了。执行
brew update
并重新再试一次。
10.2.4 MacPorts installation
If you are on a Mac and using MacPorts, all you need to do to install the Spring Boot CLI is:
如果你在Mac上使用MacPorts,安装Spring Boot CLI所有你需要做的是:
1 | $ sudo port install spring-boot-cli |
10.2.5 Command-line completion
Spring Boot CLI ships with scripts that provide command completion for BASH and zsh shells. You can source
the script (also named spring
) in any shell, or put it in your personal or system-wide bash completion initialization. On a Debian system the system-wide scripts are in /shell-completion/bash
and all scripts in that directory are executed when a new shell starts. To run the script manually, e.g. if you have installed using SDKMAN!
Spring Boot CLI附带的脚本为BASH和zsh shells提供了命令行实现。你可以在任何shell中source
脚本(也称为spring
),或将它放在用户或系统范围内的bash完成初始化。在Debian系统中系统范围内的脚本是在/shell-completion/bash
目录中,当新shell启动时,目录下的所有脚本都被执行。如果你装了SDKMAN!,为了手动运行脚本,执行下面的命令:
1 | $ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring |
If you install Spring Boot CLI using Homebrew or MacPorts, the command-line completion scripts are automatically registered with your shell.
如果你想使用Homebrew或MacPorts安装Spring Boot CLI,命令行完成脚本会自动在shell中注册。
10.2.6 Quick start Spring CLI example
Here’s a really simple web application that you can use to test your installation. Create a file called app.groovy
:
这儿有一个真实的简单的web应用,你可以用来测试你的安装。创建一个文件叫app.groovy
:
1 | @RestController |
Then simply run it from a shell:
然后简单的从shell中运行它:
1 | $ spring run app.groovy |
It will take some time when you first run the application as dependencies are downloaded. Subsequent runs will be much quicker.
当你第一次运行应用时它需要一段时间,因为要下载依赖。接下来运行会更快。
Open localhost:8080 in your favorite web browser and you should see the following output:
在你最喜欢的浏览器中输入localhost:8080,你应该会看到下面的结果:
1 | Hello World! |
10.3 Upgrading from an earlier version of Spring Boot
If you are upgrading from an earlier release of Spring Boot check the “release notes” hosted on the project wiki. You’ll find upgrade instructions along with a list of “new and noteworthy” features for each release.
如果正在升级你的Spring Boot,检查project wiki中的『发布说明』。你将找到升级说明,说明中有每一次发布的特性列表。
To upgrade an existing CLI installation use the appropriate package manager command (for example brew upgrade
) or, if you manually installed the CLI, follow the standard instructions remembering to update your PATH environment variable to remove any older references.
为了升级现有的CLI,要使用合适的包管理命令(例如brew upgrade
),如果你手动安装的CLI,要按照标准的说明去做,为了移除旧的引用要记住更新你的PATH环境变量。
11. Developing your first Spring Boot application
Let’s develop a simple “Hello World!” web application in Java that highlights some of Spring Boot’s key features. We’ll use Maven to build this project since most IDEs support it.
我们用Java开发一个简单的Web应用“Hello World!”,通过应用来强调Spring Boot的一些关键特性。由于大多数IDE都支持Maven,因此我们用Maven来构建这个项目。
The spring.io web site contains many “Getting Started” guides that use Spring Boot. If you’re looking to solve a specific problem; check there first.
You can shortcut the steps below by going to start.spring.io and choosing the
web
starter from the dependencies searcher. This will automatically generate a new project structure so that you can start coding right the way. Check the documentation for more details.
spring.io网站上有许多使用Spring Boot的“Getting Started”指南。如果你要解决一个特定的问题;先去网站上看一下。
你可以通过到start.spring.io上并从依赖搜索器中选择
web
启动器来简化下面的步骤。这会自动的产生一个新的工程结构所以你能以正确的方式开始编码。更多细节请看文档。
Before we begin, open a terminal to check that you have valid versions of Java and Maven installed.
在开始之前,打开终端检查一下,确保你已经安装了合适的Java版本和Maven版本。
1 | $ java -version |
1 | $ mvn -v |
This sample needs to be created in its own folder. Subsequent instructions assume that you have created a suitable folder and that it is your “current directory”.
这个例子需要创建它自己的文件夹。接下来的介绍假设你已经创建了合适的文件夹并且文件夹是你的当前目录。
11.1 Creating the POM
We need to start by creating a Maven pom.xml
file. The pom.xml
is the recipe that will be used to build your project. Open your favorite text editor and add the following:
我们首先需要创建一个Maven的pom.xml
文件。pom.xml
是用来构建项目的处方。打开你最喜欢的文本编辑器并添加以下内容:
1 | <?xml version="1.0" encoding="UTF-8"?> |
This should give you a working build, you can test it out by running mvn package
(you can ignore the “jar will be empty - no content was marked for inclusion!” warning for now).
这应该给你一个工作,你可以通过运行mvn package
来测试一下(你可以忽略警告“jar will be empty - no content was marked for inclusion!”)。
At this point you could import the project into an IDE (most modern Java IDE’s include built-in support for Maven). For simplicity, we will continue to use a plain text editor for this example.
在这个地方你可以将工程导入到IDE中(大多数Java IDE都有对Maven的内置支持)。为了简便,在这个例子中我们将继续使用普通的文本编辑器。
11.2 Adding classpath dependencies
Spring Boot provides a number of “Starters” that make easy to add jars to your classpath. Our sample application has already used spring-boot-starter-parent
in the parent
section of the POM. The spring-boot-starter-parent
is a special starter that provides useful Maven defaults. It also provides a dependency-management section so that you can omit version tags for “blessed” dependencies.
Spring Boot提供了许多“Starters”,这样可以很容器的在classpath中添加jar包。我们的例子程序已经在POM的parent
部分使用了spring-boot-starter-parent
。spring-boot-starter-parent
是一个特别的启动器,它能提供有用的Maven默认设置。它也提供了依赖管理部分,因此你可以对“blessed”依赖忽略其版本标签。
Other “Starters” simply provide dependencies that you are likely to need when developing a specific type of application. Since we are developing a web application, we will add a spring-boot-starter-web
dependency — but before that, let’s look at what we currently have.
当开发一个特定的应用时,其它的“Starters”简单的提供了你可能需要的依赖。由于我们正在开发一个web应用,我们将添加spring-boot-starter-web
依赖——但在那之前,让我们先看一下目前有什么。
1 | $ mvn dependency:tree |
The mvn dependency:tree
command prints a tree representation of your project dependencies. You can see that spring-boot-starter-parent
provides no dependencies by itself. Let’s edit our pom.xml
and add the spring-boot-starter-web
dependency just below the parent section:
mvn dependency:tree
命令将你的工程依赖打印成一棵树的形式。你可以看到spring-boot-starter-parent
本身没有提供依赖。让我们编辑pom.xml
文件并parent部分添加spring-boot-starter-web
依赖:
1 | <dependencies> |
If you run mvn dependency:tree
again, you will see that there are now a number of additional dependencies, including the Tomcat web server and Spring Boot itself.
如果你再运行mvn dependency:tree
,你将看到许多额外的依赖,包括Tomcat服务器和Spring Boot本身。
11.3 Writing the code
To finish our application we need to create a single Java file. Maven will compile sources from src/main/java
by default so you need to create that folder structure, then add a file named src/main/java/Example.java
:
为了完成我们的应用,我们需要创建一个简单的Java文件。Maven默认的将从src/main/java
编译源码,因此你需要创建文件结构,然后添加名为src/main/java/Example.java
的文件:
1 | import org.springframework.boot.*; |
Although there isn’t much code here, quite a lot is going on. Let’s step through the important parts.
尽管这儿没有太多代码,但已经发生了许多事情。让我们一步步浏览这些重要的部分。
11.3.1 The @RestController and @RequestMapping annotations
The first annotation on our Example
class is @RestController
. This is known as a stereotype annotation. It provides hints for people reading the code, and for Spring, that the class plays a specific role. In this case, our class is a web @Controller
so Spring will consider it when handling incoming web requests.
Example
类中的第一个注解是@RestController
。这是一个模式化的注解。它为阅读代码的人提供了暗示,对于Spring而言,这个类有一个特定的任务。在这个例子中,我们的类是一个web @Controller
,当web请求到来时,Spring会考虑用它来处理。
The @RequestMapping
annotation provides “routing” information. It is telling Spring that any HTTP request with the path “/” should be mapped to the home
method. The @RestController
annotation tells Spring to render the resulting string directly back to the caller.
@RequestMapping
注解提供了『路由』信息。它告诉Spring任何带有路径”/“的HTTP请求应该映射到home
方法上。@RestController
注解告诉Spring将结果渲染成字符串形式并直接返回给调用者。
The
@RestController
and@RequestMapping
annotations are Spring MVC annotations (they are not specific to Spring Boot). See the MVC section in the Spring Reference Documentation for more details.
@RestController
和@RequestMapping
是Spring MVC注解(它们不是Spring Boot特有的)。更多细节请看Spring参考文档中MVC部分。
11.3.2 The @EnableAutoConfiguration annotation
The second class-level annotation is @EnableAutoConfiguration
. This annotation tells Spring Boot to “guess” how you will want to configure Spring, based on the jar dependencies that you have added. Since spring-boot-starter-web
added Tomcat and Spring MVC, the auto-configuration will assume that you are developing a web application and setup Spring accordingly.
第二个类级别的注解是@EnableAutoConfiguration
。这个注解告诉Spring Boot基于你添加的jar依赖去”猜”你想怎样配置Spring。由于spring-boot-starter-web
添加了Tomcat和Spring MVC,自动配置会假设你正在开发一个web应用并相应的设置Spring。
Starters and Auto-Configuration
Auto-configuration is designed to work well with “Starters”, but the two concepts are not directly tied. You are free to pick-and-choose jar dependencies outside of the starters and Spring Boot will still do its best to auto-configure your application.
启动器和自动化配置
自动配置被设计成跟『启动器』能一起工作的很好,但这两个概念没有直接联系。你可以自由的挑选启动器之外的jar依赖,Spring Boot仍会最大程度地自动配置你的应用。
11.3.3 The “main” method
The final part of our application is the main
method. This is just a standard method that follows the Java convention for an application entry point. Our main
method delegates to Spring Boot’s SpringApplication
class by calling run
. SpringApplication
will bootstrap our application, starting Spring which will in turn start the auto-configured Tomcat web server. We need to pass Example.class
as an argument to the run
method to tell SpringApplication
which is the primary Spring component. The args
array is also passed through to expose any command-line arguments.
程序的最后部分是main
方法。这是一个符合Java应用程序入口规范的标准方法。main
方法中委托Spring Boot的SpringApplication
类调用run
方法。SpringApplication
将引导我们的应用启动Spring,Spring将启动自动配置的Tomcat web服务器。我们需要将Example.class
作为参数传给run
方法,告诉SpringApplication
它是主要的Spring组件。args
数组会将所有命令行参数传给run
方法。
11.4 Running the example
At this point our application should work. Since we have used the spring-boot-starter-parent
POM we have a useful run
goal that we can use to start the application. Type mvn spring-boot:run
from the root project directory to start the application:
此时我们的应用应该工作了。既然我们已经使用了spring-boot-starter-parent
POM,那我们有一个有用的run
目标,我们使用它来启动应用。在工程的根目录中输入mvn spring-boot:run
来启动应用。
1 | $ mvn spring-boot:run |
If you open a web browser to localhost:8080
you should see the following output:
如果你打开一个web浏览器,输入localhost:8080
,你应该会看到下面的输出。
1 | Hello World! |
To gracefully exit the application hit ctrl-c
.
可以点击ctrl-c
退出应用。
11.5 Creating an executable jar
Let’s finish our example by creating a completely self-contained executable jar file that we could run in production. Executable jars (sometimes called “fat jars”) are archives containing your compiled classes along with all of the jar dependencies that your code needs to run.
通过创建一个在产品中能运行的完整的自包含可执行jar文件来结束我们的例子。可执行jars(有时称为“fat jars”)是包含编译的类和代码运行需要的所有jar依赖的存档文件。
Executable jars and Java
Java does not provide any standard way to load nested jar files (i.e. jar files that are themselves contained within a jar). This can be problematic if you are looking to distribute a self-contained application.
Java没有提供任何标准方法来加载嵌套的jar文件(例如,jar文件本身包含在一个一个jar中)。如果你想分发一个自包含的应用,这可能是个问题。
To solve this problem, many developers use “uber” jars. An uber jar simply packages all classes, from all jars, into a single archive. The problem with this approach is that it becomes hard to see which libraries you are actually using in your application. It can also be problematic if the same filename is used (but with different content) in multiple jars.
为了解决这个问题,许多开发者使用“uber” jars。uber jar简单的将所有jars的所有类打包到一个单独的存档文件中。这个方法的问题是很难看到你的应用正在使用的是哪个库。如果多个jars使用了相同的文件名(不同的内容)也是个问题。
Spring Boot takes a different approach and allows you to actually nest jars directly.
Spring Boot采用了一种不同的方法来处理这个问题,允许你真正的直接内嵌jars。
To create an executable jar we need to add the spring-boot-maven-plugin
to our pom.xml
. Insert the following lines just below the dependencies
section:
为了创建可执行jar,我们需要添加spring-boot-maven-plugin
到pom.xml
中。在dependencies
部分下面插入以下内容:
1 | <build> |
The
spring-boot-starter-parent
POM includes<executions>
configuration to bind therepackage
goal. If you are not using the parent POM you will need to declare this configuration yourself. See the plugin documentation for details.
spring-boot-starter-parent
POM包含绑定repackage
目标的<executions>
配置。如果你没有使用父POM,那你需要自己声明这个配置。更多细节请看插件文档。
Save your pom.xml
and run mvn package
from the command line:
保存你的pom.xml
并从命令行中运行mvn package
:
1 | $ mvn package |
If you look in the target
directory you should see myproject-0.0.1-SNAPSHOT.jar
. The file should be around 10 Mb in size. If you want to peek inside, you can use jar tvf
:
如果你看一下目录target
你应该看到myproject-0.0.1-SNAPSHOT.jar
。这个文件大小应该在10 Mb左右。如果你想看里面的内容,你可以使用:jar tvf
1 | $ jar tvf target/myproject-0.0.1-SNAPSHOT.jar |
You should also see a much smaller file named myproject-0.0.1-SNAPSHOT.jar.original
in the target
directory. This is the original jar file that Maven created before it was repackaged by Spring Boot.
你在target
目录中应该也能看到一个更小的名为myproject-0.0.1-SNAPSHOT.jar.original
的文件。这是Spring Boot repackage之前Maven创建的最初的jar文件。
To run that application, use the java -jar
command:
为了运行这个应用,要使用java -jar
命令:
1 | $ java -jar target/myproject-0.0.1-SNAPSHOT.jar |
As before, to gracefully exit the application hit ctrl-c
.
像前面一样,通过点击ctrl-c
来退出应用。
12. What to read next
Hopefully this section has provided you with some of the Spring Boot basics, and got you on your way to writing your own applications. If you’re a task-oriented type of developer you might want to jump over to spring.io and check out some of the getting started guides that solve specific “How do I do that with Spring” problems; we also have Spring Boot-specific How-to reference documentation.
希望这部分内容给你提供了一些Spring Boot的基本知识,让你写了你自己的应用。如果你是一个面向任务的开发人员,你可能想跳到spring.io,找出一些getting started指南来解决特定的『用Spring怎样做』的问题;我们也提供了Spring Boot的How-to参考文档。
The Spring Boot repository has also a bunch of samples you can run. The samples are independent of the rest of the code (that is you don’t need to build the rest to run or use the samples).
Spring Boot repository也有一些你可以运行的例子。例子是独立于其它代码的(运行或使用例子时你不需要构建其它的内容)。
Otherwise, the next logical step is to read Part III, “Using Spring Boot”. If you’re really impatient, you could also jump ahead and read about Spring Boot features.
此外,按逻辑接下来是读第三部分,『使用Spring Boot』。如果你真的不耐烦,你也跳过这部分,直接阅读Spring Boot的特性。
Part III. Using Spring Boot
This section goes into more detail about how you should use Spring Boot. It covers topics such as build systems, auto-configuration and how to run your applications. We also cover some Spring Boot best practices. Although there is nothing particularly special about Spring Boot (it is just another library that you can consume), there are a few recommendations that, when followed, will make your development process just a little easier.
这一节将会讲述关于应该如何使用Spring Boot的更多细节。它包括许多主题例如构建系统,自动配置和怎么运行自己的应用。我们也讲述一些Spring Boot的最佳实践。虽然没有关于Spring Boot非常特别的东西(它只是另一个你可以使用的库),但接下来的一些建议可以让你的开发过程更容易一点。
If you’re just starting out with Spring Boot, you should probably read the Getting Started guide before diving into this section.
如果你刚开始学习Spring Boot,在学习这节之前你可能应该先阅读一下『Getting Started』部分。
13. Build systems
It is strongly recommended that you choose a build system that supports dependency management, and one that can consume artifacts published to the “Maven Central” repository. We would recommend that you choose Maven or Gradle. It is possible to get Spring Boot to work with other build systems (Ant for example), but they will not be particularly well supported.
强烈建议你选择一个支持依赖管理的构建系统,构建系统可以使用发布在『Maven Central』仓库中的工件。我们建议你选择Maven或Gradle。Spring Boot可能也可以与其它的构建系统进行协作(例如Ant),但不能特别好的支持其它的构建系统。
13.1 Dependency management
Each release of Spring Boot provides a curated list of dependencies it supports. In practice, you do not need to provide a version for any of these dependencies in your build configuration as Spring Boot is managing that for you. When you upgrade Spring Boot itself, these dependencies will be upgraded as well in a consistent way.
Spring Boot的每一次发布都会提供它支持的依赖列表。实际应用时,在你的构建配置中不需要提供这些依赖的版本,因为Spring Boot会帮你进行管理。当你升级Spring Boot时,这些依赖也会随之进行升级。
You can still specify a version and override Spring Boot’s recommendations if you feel that’s necessary.
如果有必要的话,你仍可以指定版本并覆盖Spring Boot的推荐。
The curated list contains all the spring modules that you can use with Spring Boot as well as a refined list of third party libraries. The list is available as a standard Bills of Materials (spring-boot-dependencies) and additional dedicated support for Maven and Gradle are available as well.
这个列表包含了所有你在Spring Boot中可以使用的Spring模块,也包含了第三方库的精制列表。这个列表可以当做一个标准可用的Bills of Materials (spring-boot-dependencies),也额外的专门支持Maven和Gradle可用。
Each release of Spring Boot is associated with a base version of the Spring Framework so we highly recommend you to not specify its version on your own.
Spring Boot的每一次发布都是与Spring框架的基本版本相关的,因此我们强烈建议你在自己使用时不要指定它的版本。
13.2 Maven
Maven users can inherit from the spring-boot-starter-parent
project to obtain sensible defaults. The parent project provides the following features:
Java 1.6 as the default compiler level.
UTF-8 source encoding.
A Dependency Management section, allowing you to omit
<version>
tags for common dependencies, inherited from thespring-boot-dependencies
POM.Sensible resource filtering.
Sensible plugin configuration (exec plugin, surefire, Git commit ID, shade).
Sensible resource filtering for
application.properties
andapplication.yml
including profile-specific files (e.g.application-foo.properties
andapplication-foo.yml
)
Maven用户可以继承spring-boot-starter-parent
工程来获得合理的默认配置。父工程提供了下面的特性:
Java 1.6作为默认的编译级别。
UTF-8源码编码。
依赖管理部分,对于常用的依赖允许你忽略
<version>
标签,从spring-boot-dependencies
继承POM。合理的资源过滤。
合理的插件配置(exec plugin, surefire, Git commit ID, shade)。
对包括特定配置文件的
application.properties
和application.yml
的合理资源过滤(例如,application-foo.properties
和application-foo.yml
)。
On the last point: since the default config files accept Spring style placeholders (${…}
) the Maven filtering is changed to use @..@
placeholders (you can override that with a Maven property resource.delimiter
).
最后一点:由于默认配置文件采用Spring风格的占位符(${…}
),Maven过滤改成了使用@..@
占位符(你可以使用Maven属性resource.delimiter
来覆盖)。
13.2.1 Inheriting the starter parent
To configure your project to inherit from the spring-boot-starter-parent
simply set the parent
:
为了配置你的工程继承spring-boot-starter-parent
,简单的设置parent
:
1 | <!-- Inherit defaults from Spring Boot --> |
You should only need to specify the Spring Boot version number on this dependency. If you import additional starters, you can safely omit the version number.
你应该只需要在这个依赖中指定Spring Boot的版本号。如果你导入额外的starters,你可以安全的忽略这个版本号。
With that setup, you can also override individual dependencies by overriding a property in your own project. For instance, to upgrade to another Spring Data release train you’d add the following to your pom.xml
.
有了这个设置,你也可以通过在你的工程中重写一个属性来覆盖单独的依赖。例如,为了升级另一个Spring Data的发布版本,你将需要在你的pom.xml
中添加以下内容:
1 | <properties> |
Check the
spring-boot-dependencies
pom for a list of supported properties.
检查
spring-boot-dependencies
pom支持的属性清单。
13.2.2 Using Spring Boot without the parent POM
Not everyone likes inheriting from the spring-boot-starter-parent
POM. You may have your own corporate standard parent that you need to use, or you may just prefer to explicitly declare all your Maven configuration.
不是每个人都喜欢继承spring-boot-starter-parent
POM的。你也可以有需要使用的公司的标准父POM,或者你可能更喜欢显式的声明你所有的Maven配置。
If you don’t want to use the spring-boot-starter-parent
, you can still keep the benefit of the dependency management (but not the plugin management) by using a scope=import
dependency:
如果你不想使用spring-boot-starter-parent
,但你仍要保留依赖管理的好处(不是插件管理),你可以使用scope=import
依赖:
1 | <dependencyManagement> |
That setup does not allow you to override individual dependencies using a property as explained above. To achieve the same result, you’d need to add an entry in the dependencyManagement
of your project before the spring-boot-dependencies
entry. For instance, to upgrade to another Spring Data release train you’d add the following to your pom.xml
.
这个设置不允许你使用上面阐述的属性来重写单独的依赖。为了取得同样的效果,你需要在spring-boot-dependencies
入口之前在工程的dependencyManagement
中的添加一个入口。为了升级另一个Spring Data的发布版本,你将需要在你的pom.xml
中添加以下内容:
1 | <dependencyManagement> |
In the example above, we specify a BOM but any dependency type can be overridden that way.
在上面的例子中,我们指定了一个POM但任何依赖类型都可以被重写。
13.2.3 Changing the Java version
The spring-boot-starter-parent
chooses fairly conservative Java compatibility. If you want to follow our recommendation and use a later Java version you can add a java.version
property:
spring-boot-starter-parent
选择了相当保守的Java兼容性。如果你想听从我们的建议,使用更新的Java版本,你可以添加java.version
属性。
1 | <properties> |
13.2.4 Using the Spring Boot Maven plugin
Spring Boot includes a Maven plugin that can package the project as an executable jar. Add the plugin to your <plugins>
section if you want to use it:
Spring Boot包含了一个Maven插件,这个插件可以将工程打包为一个可执行的jar包。如果你向使用它的话,将它添加到你的<plugins>
部分:
1 | <build> |
If you use the Spring Boot starter parent pom, you only need to add the plugin, there is no need for to configure it unless you want to change the settings defined in the parent.
如果你想使用Spring Boot的starter parent pom,你只需要添加这个插件,不需要配置它,除非你想更改父POM中的定义的设置。
13.3 Gradle
Gradle users can directly import starters
in their dependencies
section. Unlike Maven, there is no “super parent” to import to share some configuration.
Gradle用户可以直接在它们的dependencies
部分导入starters
。不像Maven,这儿不能导入“super parent”来共享一些配置。
1 | apply plugin: 'java' |
The spring-boot-gradle-plugin
is also available and provides tasks to create executable jars and run projects from source. It also provides dependency management that, among other capabilities, allows you to omit the version number for any dependencies that are managed by Spring Boot:
spring-boot-gradle-plugin
也可用,并提供了从源码创建可执行jars和运行项目的功能。它也提供了依赖管理,在其它的兼容性之间,允许你忽略任何Spring Boot管理的依赖的版本号:
1 | buildscript { |
13.4 Ant
It is possible to build a Spring Boot project using Apache Ant+Ivy. The spring-boot-antlib
“AntLib” module is also available to help Ant create executable jars.
使用Apache Ant+Ivy来创建一个Spring Boot项目是可能的。spring-boot-antlib
“AntLib”模块也可以用来帮助Ant创建可执行jars。
To declare dependencies a typical ivy.xml
file will look something like this:
为了声明依赖,一个典型的ivy.xml
文件如下:
1 | <ivy-module version="2.0"> |
A typical build.xml
will look like this:
一个典型build.xml
如下所示:
1 | <project |
See the Section 79.10, “Build an executable archive from Ant without using spring-boot-antlib” “How-to” if you don’t want to use the
spring-boot-antlib
module.
如果你不想使用
spring-boot-antlib
模块,请看79.10小节,“Build an executable archive from Ant without using spring-boot-antlib” “How-to”。
13.5 Starters
Starters are a set of convenient dependency descriptors that you can include in your application. You get a one-stop-shop for all the Spring and related technology that you need, without having to hunt through sample code and copy paste loads of dependency descriptors. For example, if you want to get started using Spring and JPA for database access, just include the spring-boot-starter-data-jpa
dependency in your project, and you are good to go.
启动器是一系列你可以包含进自己应用中的实用依赖描述符。你可以得到所有Spring和你需要的相关技术的一站式服务,不需要有搜索样例代码和拷贝粘贴依赖描述符的负担。例如,如果你想开始使用Spring和JPA来进行数据库链接,只需要在你的工程中包含spring-boot-starter-data-jpa
依赖,你便可以很好的前行了。
The starters contain a lot of the dependencies that you need to get a project up and running quickly and with a consistent, supported set of managed transitive dependencies.
启动器包含许多你需要启动并快速运行一个工程的依赖,并持续支持一系列传递管理的依赖。
What’s in a name
All official starters follow a similar naming pattern; spring-boot-starter-*
, where *
is a particular type of application. This naming structure is intended to help when you need to find a starter. The Maven integration in many IDEs allow you to search dependencies by name. For example, with the appropriate Eclipse or STS plugin installed, you can simply hit ctrl-space
in the POM editor and type “spring-boot-starter” for a complete list.
所有的官方启动器都有一个类似的命名模式:spring-boot-starter-*
,*
是应用的特性类型。这个命名结构用来在你需要时帮助你发现一个启动器。Maven在许多IDEs中进行了集成,允许你通过名字来搜索依赖。例如,安装了合适的Eclipse或STS插件,你可以简单的在POM编辑器中点击ctrl-space
并输入“spring-boot-starter”来查找一个完整的列表。
As explained in the Creating your own starter section, third party starters should not start with spring-boot
as it is reserved for official Spring Boot artifacts. A third-party starter for acme
will be typically named acme-spring-boot-starter
.
正如在创建你自己的启动器部分讲述的那样,第三方启动器不应该与spring-boot
一起启动,因为它是预留给官方Spring Boot构建的。acme
的第三方启动器通过命名为acme-spring-boot-starter
。
The following application starters are provided by Spring Boot under the org.springframework.boot
group:
下面的应用启动器由Spring Boot提供,在org.springframework.boot
组下:
Table 13.1. Spring Boot application starters
Name | Description | POM |
---|---|---|
spring-boot-starter-thymeleaf | Starter for building MVC web applications using Thymeleaf views | POM |
spring-boot-starter-data-couchbase | Starter for using Couchbase document-oriented database and Spring Data Couchbase | POM |
spring-boot-starter-artemis | Starter for JMS messaging using Apache Artemis | POM |
spring-boot-starter-web-services | Starter for using Spring Web Services | POM |
spring-boot-starter-mail | Starter for using Java Mail and Spring Framework’s email sending support | POM |
spring-boot-starter-data-redis|Starter for using Redis key-value data store with Spring Data Redis and the Jedis client|POM|
spring-boot-starter-web|Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container|
POM|
|spring-boot-starter-data-gemfire|Starter for using GemFire distributed data store and Spring Data GemFire|POM|
|spring-boot-starter-activemq|Starter for JMS messaging using Apache ActiveMQ|POM|
|spring-boot-starter-data-elasticsearch|Starter for using Elasticsearch search and analytics engine and Spring Data Elasticsearch|POM|
|spring-boot-starter-integration|Starter for using Spring Integration|POM|
|spring-boot-starter-test|Starter for testing Spring Boot applications with libraries including JUnit, Hamcrest and Mockito|POM|
|spring-boot-starter-jdbc|Starter for using JDBC with the Tomcat JDBC connection pool|POM|
|spring-boot-starter-mobile|Starter for building web applications using Spring Mobile|POM|
|spring-boot-starter-validation|Starter for using Java Bean Validation with Hibernate Validator|POM|
|spring-boot-starter-hateoas|Starter for building hypermedia-based RESTful web application with Spring MVC and Spring HATEOAS|POM|
|spring-boot-starter-jersey|Starter for building RESTful web applications using JAX-RS and Jersey. An alternative to spring-boot-starter-web|POM|
|spring-boot-starter-data-neo4j|Starter for using Neo4j graph database and Spring Data Neo4j|POM|
|spring-boot-starter-websocket|Starter for building WebSocket applications using Spring Framework’s WebSocket support|POM|
|spring-boot-starter-aop|Starter for aspect-oriented programming with Spring AOP and AspectJ|POM|
|spring-boot-starter-amqp|Starter for using Spring AMQP and Rabbit MQ|POM|
|spring-boot-starter-data-cassandra|Starter for using Cassandra distributed database and Spring Data Cassandra|POM|
|spring-boot-starter-social-facebook|Starter for using Spring Social Facebook|POM|
|spring-boot-starter-jta-atomikos|Starter for JTA transactions using Atomikos|POM|
|spring-boot-starter-security|Starter for using Spring Security|POM|
|spring-boot-starter-mustache|Starter for building MVC web applications using Mustache views|POM|
|spring-boot-starter-data-jpa|Starter for using Spring Data JPA with Hibernate|POM|
|spring-boot-starter|Core starter, including auto-configuration support, logging and YAML|POM|
|spring-boot-starter-groovy-templates|Starter for building MVC web applications using Groovy Templates views|POM|
|spring-boot-starter-freemarker|Starter for building MVC web applications using FreeMarker views|POM|
|spring-boot-starter-batch|Starter for using Spring Batch|POM|
|spring-boot-starter-social-linkedin|Stater for using Spring Social LinkedIn|POM|
|spring-boot-starter-cache|Starter for using Spring Framework’s caching support|POM|
|spring-boot-starter-data-solr|Starter for using the Apache Solr search platform with Spring Data Solr|POM|
|spring-boot-starter-data-mongodb|Starter for using MongoDB document-oriented database and Spring Data MongoDB|POM|
|spring-boot-starter-jooq|Starter for using jOOQ to access SQL databases. An alternative to spring-boot-starter-data-jpa or spring-boot-starter-jdbc|POM|
|spring-boot-starter-jta-narayana|Spring Boot Narayana JTA Starter|POM|
|spring-boot-starter-cloud-connectors|Starter for using Spring Cloud Connectors which simplifies connecting to services in cloud platforms like Cloud Foundry and Heroku|POM|
|spring-boot-starter-jta-bitronix|Starter for JTA transactions using Bitronix|POM|
|spring-boot-starter-social-twitter|Starter for using Spring Social Twitter|POM|
|spring-boot-starter-data-rest|Starter for exposing Spring Data repositories over REST using Spring Data REST|POM|
In addition to the application starters, the following starters can be used to add production ready features:
除了应用启动器之外,下面的启动器可以用来添加产品准备功能:
Table 13.2. Spring Boot production starters
Name | Description | Pom |
---|---|---|
spring-boot-starter-actuator | Starter for using Spring Boot’s Actuator which provides production ready features to help you monitor and manage your application | Pom |
Finally, Spring Boot also includes some starters that can be used if you want to exclude or swap specific technical facets:
最后,如果你想排除或交换特定的技术方面,Spring Boot也包括一些可以使用的启动器:
Table 13.3. Spring Boot technical starters
Name | Description | Pom |
---|---|---|
spring-boot-starter-undertow | Starter for using Undertow as the embedded servlet container. An alternative to spring-boot-starter-tomcat | Pom |
spring-boot-starter-jetty | Starter for using Jetty as the embedded servlet container. An alternative to spring-boot-starter-tomcat | Pom |
spring-boot-starter-logging | Starter for logging using Logback. Default logging starter | Pom |
spring-boot-starter-tomcat | Starter for using Tomcat as the embedded servlet container. Default servlet container starter used by spring-boot-starter-web |
Pom |
spring-boot-starter-log4j2 | Starter for using Log4j2 for logging. An alternative to spring-boot-starter-logging |
Pom |
For a list of additional community contributed starters, see the README file in
the spring-boot-starters
module on GitHub.
对于额外的社区共享的启动器,请看GitHub上
the spring-boot-starters
模块的README file。
14. Structuring your code
Spring Boot does not require any specific code layout to work, however, there are some best practices that help.
Spring Boot工作时不要求任何特定的代码布局,但是有一些最佳实践是很有帮助的。
14.1 Using the “default” package
When a class doesn’t include a package
declaration it is considered to be in the “default package”. The use of the “default package” is generally discouraged, and should be avoided. It can cause particular problems for Spring Boot applications that use @ComponentScan
, @EntityScan
or @SpringBootApplication
annotations, since every class from every jar, will be read.
当一个类没有包含一个package
声明时,它当做是在default package
中。通常情况下不建议使用default package
,应该避免使用它。当Spring Boot应用使用@ComponentScan
,@EntityScan
或@SpringBootApplication
它会引起一些特别的问题,因为Spring Boot会读取每个jar中的每个类。
We recommend that you follow Java’s recommended package naming conventions and use a reversed domain name (for example,
com.example.project
).
我们建议你遵循Java推荐的包命名规范,使用一个反转的域名(例如,
com.example.project
)。
14.2 Locating the main application class
We generally recommend that you locate your main application class in a root package above other classes. The @EnableAutoConfiguration
annotation is often placed on your main class, and it implicitly defines a base “search package” for certain items. For example, if you are writing a JPA application, the package of the @EnableAutoConfiguration
annotated class will be used to search for @Entity
items.
通常我们建议你将你的主应用类放在其它类之上的根包中。@EnableAutoConfiguration
注解经常放在你的主类(main class)中,对于某些像它隐式的定义了一个基search package
,例如,如果你正在写一个JPA应用,@EnableAutoConfiguration
注解的类所在的包将被用来搜索@Entity
项。
Using a root package also allows the @ComponentScan
annotation to be used without needing to specify a basePackage
attribute. You can also use the @SpringBootApplication
annotation if your main class is in the root package.
根包的应用也允许使用@ComponentScan
注解而不需要指定basePackage
特性。如果你的主类是在根包中,你也可以使用@SpringBootApplication
注解。
Here is a typical layout:
下面是一个典型的布局:
1 | com |
The Application.java
file would declare the main
method, along with the basic @Configuration
.
Application.java
文件会声明main
方法和基本的@Configuration
。
1 | package com.example.myproject; |
15. Configuration classes
Spring Boot favors Java-based configuration. Although it is possible to call SpringApplication.run()
with an XML source, we generally recommend that your primary source is a @Configuration
class. Usually the class that defines the main
method is also a good candidate as the primary @Configuration
.
Spring Boot支持基于Java的注解。尽管可以通过XML源调用SpringApplication.run()
方法,但我们通常建议你主要的源是一个@Configuration
类。
Many Spring configuration examples have been published on the Internet that use XML configuration. Always try to use the equivalent Java-based configuration if possible. Searching for
enable*
annotations can be a good starting point.
网上已经发布了许多使用XML配置来进行Spring配置的例子。但要尽可能的尝试使用等价的Java注解。搜索
enable*
注解是一个好的开端。
15.1 Importing additional configuration classes
You don’t need to put all your @Configuration
into a single class. The @Import
annotation can be used to import additional configuration classes. Alternatively, you can use @ComponentScan
to automatically pick up all Spring components, including @Configuration
classes.
你不必将所有的@Configuration
放到一个单独的类中。可以使用@Import
注解来导入额外的配置类。或者,你可以使用@ComponentScan
来自动获得所有的Spring组件,包括@Configuration
类。
15.2 Importing XML configuration
If you absolutely must use XML based configuration, we recommend that you still start with a @Configuration
class. You can then use an additional @ImportResource
annotation to load XML configuration files.
如果你绝对的必须使用基于XML的配置,我们推荐你仍然从@Configuration
类开始。你可以使用额外的@ImportResource
注解来加载XML配置文件。
16. Auto-configuration
Spring Boot auto-configuration attempts to automatically configure your Spring application based on the jar dependencies that you have added. For example, If HSQLDB
is on your classpath, and you have not manually configured any database connection beans, then we will auto-configure an in-memory database.
Spring Boot自动配置会基于你添加的jar依赖试图自动配置你的Spring应用。例如,如果HSQLDB
在你的classpath中,并且你没有手动的配置任何数据库连接beans,我们将会在自动配置一个内存中的数据库。
You need to opt-in to auto-configuration by adding the @EnableAutoConfiguration
or @SpringBootApplication
annotations to one of your @Configuration
classes.
你需要通过添加@EnableAutoConfiguration
或@SpringBootApplication
注解到你的@Configuration
类中的一个来选择性的加入自动配置。
You should only ever add one
@EnableAutoConfiguration
annotation. We generally recommend that you add it to your primary@Configuration
class.
你应该仅添加一个
@EnableAutoConfiguration
注解。我们通常建议你将它添加到你主要的@Configuration
类中。
16.1 Gradually replacing auto-configuration
Auto-configuration is noninvasive, at any point you can start to define your own configuration to replace specific parts of the auto-configuration. For example, if you add your own DataSource
bean, the default embedded database support will back away.
自动配置是非入侵性的,在任何时候你都可以开始定义你自己的配置来替换自动配置的指定部分。例如,如果你要添加你自己的DataSource
bean,默认嵌入的数据库支持将会退出。
If you need to find out what auto-configuration is currently being applied, and why, start your application with the --debug
switch. This will enable debug logs for a selection of core loggers and log an auto-configuration report to the console.
如果你需要找出当前正在应用的自动配置和为什么,你可以用--debug
开关来启动你的应用。这将会使核心日志的输出级别变为debug级别并输出一个自动配置报告到控制台。
16.2 Disabling specific auto-configuration
If you find that specific auto-configure classes are being applied that you don’t want, you can use the exclude
attribute of @EnableAutoConfiguration
to disable them.
如果你发现正在应用特定的你不想使用的自动配置类,你可以使用@EnableAutoConfiguration
注解的exclude
特性来禁用它们。
1 | import org.springframework.boot.autoconfigure.*; |
If the class is not on the classpath, you can use the excludeName
attribute of the annotation and specify the fully qualified name instead. Finally, you can also control the list of auto-configuration classes to exclude via the spring.autoconfigure.exclude
property.
如果这个类不在classpath中,你可以使用这个注解的excludeName
特性并指定全限定名来代替。最后,你也可以通过spring.autoconfigure.exclude
属性来排除,从而控制自动配置类的列表。
You can define exclusions both at the annotation level and using the property.
你也可以在注解级别或使用属性来定义排除项。
17. Spring Beans and dependency injection
You are free to use any of the standard Spring Framework techniques to define your beans and their injected dependencies. For simplicity, we often find that using @ComponentScan
to find your beans, in combination with @Autowired
constructor injection works well.
你可以自由的使用任何标准的Spring框架技术来定义你的beans和它们注入的依赖。为了简便,我们经常使用@ComponentScan
来发现你的beans,结合@Autowired
构造函数注入也工作的很好。
If you structure your code as suggested above (locating your application class in a root package), you can add @ComponentScan
without any arguments. All of your application components (@Component
, @Service
, @Repository
, @Controller
etc.) will be automatically registered as Spring Beans.
如果你根据上面的建议组织你代码(将你的应用类放在根包中),你可以添加@ComponentScan
注解而不需要任何参数。你所有的应用组件(@Component
,@Service
,@Repository
,@Controller
等等)将会作为Spring bean进行自动注册。
Here is an example @Service
Bean that uses constructor injection to obtain a required RiskAssessor
bean.
下面是一个@Service
Bean的例子,通过使用构造函数注入来获得RiskAssessor
bean。
1 | package com.example.service; |
Notice how using constructor injection allows the
riskAssessor
field to be marked asfinal
, indicating that it cannot be subsequently changed.
注意使用构造函数注入允许
riskAssessor
字段标记为final
,意味着它接下来不能被修改。
18. Using the @SpringBootApplication annotation
Many Spring Boot developers always have their main class annotated with @Configuration
, @EnableAutoConfiguration
and @ComponentScan
. Since these annotations are so frequently used together (especially if you follow the best practices above), Spring Boot provides a convenient @SpringBootApplication
alternative.
许多Spring Boot的开发者总是在它们的主类上加上@Configuration
,@EnableAutoConfiguration
和@ComponentScan
注解。由于这些注解频繁的在一起使用(尤其是你遵循上面的最佳实践时),Spring Boot提供了一个方便的@SpringBootApplication
注解来代替它们。
The @SpringBootApplication
annotation is equivalent to using @Configuration
, @EnableAutoConfiguration
and @ComponentScan
with their default attributes:
@SpringBootApplication
注解等价于使用@Configuration
,@EnableAutoConfiguration
和@ComponentScan
以及它们的默认特性:
1 | package com.example.myproject; |
@SpringBootApplication
also provides aliases to customize the attributes of@EnableAutoConfiguration
and@ComponentScan
.
@SpringBootApplication
也提供了别名来定制@EnableAutoConfiguration
和@ComponentScan
的特性。
19. Running your application
One of the biggest advantages of packaging your application as jar and using an embedded HTTP server is that you can run your application as you would any other. Debugging Spring Boot applications is also easy; you don’t need any special IDE plugins or extensions.
将应用打包成jar并使用内嵌HTTP服务器的一个最大优势是你可以在任何地方运行你的程序。调试Spring Boot应用也很容易;你不必指定任何特定的IDE插件或扩展。
This section only covers jar based packaging, If you choose to package your application as a war file you should refer to your server and IDE documentation.
这一节只包含基于jar的打包,如果你想选择将你的应用打包成war文件,你应该参考你的服务器和IDE文档。
19.1 Running from an IDE
You can run a Spring Boot application from your IDE as a simple Java application, however, first you will need to import your project. Import steps will vary depending on your IDE and build system. Most IDEs can import Maven projects directly, for example Eclipse users can select Import…
→ Existing Maven Projects
from the File
menu.
你可以在你的IDE中运行一个Spring Boot应用将像运行一个简单的Java应用一样,然而,首先你需要导入你的工程。导入步骤根据你的IDE和构建系统会有所变化。大多数IDE可以直接导入Maven工程,例如Eclipse用户可以选择从File
菜单选择Import…
→ Existing Maven Projects
。
If you can’t directly import your project into your IDE, you may be able to generate IDE metadata using a build plugin. Maven includes plugins for Eclipse and IDEA; Gradle offers plugins for various IDEs.
如果你不能直接将工程导入你的IDE中,你可以使用构建插件生成一个IDE元数据。Maven中包含Eclipse和IDEA的插件;Gradle有各种IDEs的插件。
If you accidentally run a web application twice you will see a “Port already in use” error. STS users can use the
Relaunch
button rather thanRun
to ensure that any existing instance is closed.
如果你偶然的运行一个web应用两次,你会看到一个
Port already in use
错误。为了确保任何现有的实例被关闭,STS用户可以使用Relaunch
按钮而不是Run
按钮。
19.2 Running as a packaged application
If you use the Spring Boot Maven or Gradle plugins to create an executable jar you can run your application using java -jar
. For example:
如果你使用Spring Boot的Maven或Gradle插件来创建一个可执行的jar包,你可以通过使用java -jar
来运行你的应用。例如:
1 | $ java -jar target/myproject-0.0.1-SNAPSHOT.jar |
It is also possible to run a packaged application with remote debugging support enabled. This allows you to attach a debugger to your packaged application:
它也支持以远程调试模式运行一个打包的应用。这允许你在打包的应用中添加一个调试器:
1 | $ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n -jar target/myproject-0.0.1-SNAPSHOT.jar |
19.3 Using the Maven plugin
The Spring Boot Maven plugin includes a run
goal which can be used to quickly compile and run your application. Applications run in an exploded form just like in your IDE.
Spring Boot Maven插件包含一个run
目标,可以用来快速编译并运行你的应用。应用以exploded形式运行,就像在IDE中运行一样。
1 | $ mvn spring-boot:run |
You might also want to use the useful operating system environment variable:
你也可以使用有用的操作系统环境变量:
1 | $ export MAVEN_OPTS=-Xmx1024m -XX:MaxPermSize=128M |
19.4 Using the Gradle plugin
The Spring Boot Gradle plugin also includes a bootRun
task which can be used to run your application in an exploded form. The bootRun
task is added whenever you import the spring-boot-gradle-plugin
:
Spring Boot Gradle插件也包含一个bootRun
任务,它可以以exploded方式运行你的应用。当你导入spring-boot-gradle-plugin
时,可以添加bootRun
任务:
1 | $ gradle bootRun |
You might also want to use this useful operating system environment variable:
你也可以使用有用的操作系统环境变量:
1 | $ export JAVA_OPTS=-Xmx1024m -XX:MaxPermSize=128M |
19.5 Hot swapping
Since Spring Boot applications are just plain Java applications, JVM hot-swapping should work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can replace, for a more complete solution JRebel or the Spring Loaded project can be used. The spring-boot-devtools
module also includes support for quick application restarts.
由于Spring Boot应用只是普通的Java应用,JVM热交换应该是开箱即用的。JVM热交换可以替换的字节码有限制,一个更全面的解决方案是JRebel或Spring Loaded工程。spring-boot-devtools
模块也支持快速的应用重启。
See the Chapter 20, Developer tools section below and the Hot swapping “How-to” for details.
更多细节请看20章,下面的开发者工具部分和怎样热交换部分。
20. Developer tools
Spring Boot includes an additional set of tools that can make the application development experience a little more pleasant. The spring-boot-devtools
module can be included in any project to provide additional development-time features. To include devtools support, simply add the module dependency to your build:
Spring Boot包含额外的工具集合,可以使应用开发的过程更方便一点。spring-boot-devtools
模块可以包含进任何工程,用来提供额外的程序调试特性。为了添加工具支持,简单的添加模块依赖到你的构建系统中:
Maven.
1 | <dependencies> |
Gradle.
1 | dependencies { |
Developer tools are automatically disabled when running a fully packaged application. If your application is launched using
java -jar
or if it’s started using a special classloader, then it is considered a “production application”. Flagging the dependency asoptional
is a best practice that prevents devtools from being transitively applied to other modules using your project. Gradle does not supportoptional
dependencies out-of-the-box so you may want to have a look to the propdeps-plugin in the meantime.
当运行一个完整的打包应用时,开发者工具会自动失效。如果你的应用是通过
java -jar
启动的,或者是通过一个特定的类加载器启动的,那它会被当做一个『产品级应用』。将依赖标记为optional
是阻止开发工具间接应用到使用你应用的其它模块的最佳实践。Gradle不支持optional
依赖开箱即用,同时你可能想看看propdeps-plugin。repackaged archives do not contain devtools by default. If you want to use certain remote devtools feature, you’ll need to enable the
excludeDevtools
build property to include it. The property is supported with both the Maven and Gradle plugins.
再打包文件默认不包含开发者工具。如果你想使用某些远程开发者工具特性,你需要让
excludeDevtools
构建属性包含它。Maven和Gradle插件都支持这个属性。
20.2 Automatic restart
Applications that use spring-boot-devtools
will automatically restart whenever files on the classpath change. This can be a useful feature when working in an IDE as it gives a very fast feedback loop for code changes. By default, any entry on the classpath that points to a folder will be monitored for changes. Note that certain resources such as static assets and view templates do not need to restart the application.
当classpath
中的文件修改时,使用spring-boot-devtools
的应用会自动重启。当使用IDE开发时,这是一个很有用的功能,因为代码改变时它能快速的进行反馈。默认情况下,会监控classpath
指向的文件夹中任何条目的变化。注意某些资源例如静态资源和视图模板不需要重启应用。
Triggering a restart
As DevTools monitors classpath resources, the only way to trigger a restart is to update the classpath. The way in which you cause the classpath to be updated depends on the IDE that you are using. In Eclipse, saving a modified file will cause the classpath to be updated and trigger a restart. In IntelliJ IDEA, building the project (
Build → Make Project
) will have the same effect.
触发重启
作为
DevTools
监视器classpath
中的资源,触发重启的唯一方式是更新classpath
。引起classpath
更新的方式取决于你使用的IDE。在Eclipse中,保存一个修改的文件将引起classpath
更新并触发重启事件。在IntelliJ IDEA中,构建工程(Build → Make Project
)将会有同样的效果。
You can also start your application via the supported build plugins (i.e. Maven and Gradle) as long as forking is enabled since DevTools need an isolated application classloader to operate properly. Gradle and Maven do that by default when they detect DevTools on the classpath.
只要启用了分支,你也可以通过支持的构建系统启动你的应用(例如,Maven和Gradle),因为
DevTools
需要一个独立的应用类加载器来进行正确操作。当Gradle和Maven在classpath
中检测到DevTools
时,它们默认的进行了那个工作。
Automatic restart works very well when used with
LiveReload
. See below for details. If you use JRebel automatic restarts will be disabled in favor of dynamic class reloading. Other devtools features (such asLiveReload
and property overrides) can still be used.
当使用
LiveReload
,自动重启能很好的工作。更多细节请看下面。如果你使用JRebel
进行自动重启,将不支持动态的类重加载。其它的开发者工具功能(例如LiveReload
和属性覆写)仍能继续使用。
DevTools relies on the application context’s shutdown hook to close it during a restart. It will not work correctly if you have disabled the shutdown hook (
SpringApplication.setRegisterShutdownHook(false)
).
DevTools
依赖应用上下文关闭钩子来进行重启期间的关闭。如果你禁用了关闭钩子它将不能正确工作(SpringApplication.setRegisterShutdownHook(false)
)。
When deciding if an entry on the classpath should trigger a restart when it changes, DevTools automatically ignores projects named
spring-boot
,spring-boot-devtools
,spring-boot-autoconfigure
,spring-boot-actuator
, andspring-boot-starter
.
当决定
classpath
中输入引起的改变是否应该触发重启时,DevTools
会自动忽略命名为spring-boot
,spring-boot-devtools
,spring-boot-autoconfigure
,spring-boot-actuator
和spring-boot-starter
的工程。
Restart vs Reload
The restart technology provided by Spring Boot works by using two classloaders. Classes that don’t change (for example, those from third-party jars) are loaded into a base classloader. Classes that you’re actively developing are loaded into a restart classloader. When the application is restarted, the restart classloader is thrown away and a new one is created. This approach means that application restarts are typically much faster than “cold starts” since the base classloader is already available and populated.
If you find that restarts aren’t quick enough for your applications, or you encounter classloading issues, you could consider reloading technologies such as JRebel from ZeroTurnaround. These work by rewriting classes as they are loaded to make them more amenable to reloading. Spring Loaded provides another option, however it doesn’t support as many frameworks and it isn’t commercially supported.
重启与重载(重新加载)
Spring Boot提供的重启技术是通过两个类加载器进行工作的。加载进基类加载器的类不能改变(例如,那些第三方jar包)。那些你正在开发的类加载进重启类加载器中。当应用重启时,丢弃旧的重启类加载器并创建一个新的。这种方法意味着应用重启时比『冷启动』更快,因为基类加载器已经存在并可用。
如果你发现你的应用重启不够快,或者你碰到了类加载问题,你可以考虑重载技术例如ZeroTurnaround的JRebel。这些工作通过加载时类的重写使它们更适合重载。Spring加载提供了另一种选择,但许多框架都不支持,也不支持商业化。
20.2.1 Excluding resources
Certain resources don’t necessarily need to trigger a restart when they are changed. For example, Thymeleaf templates can just be edited in-place. By default changing resources in /META-INF/maven
, /META-INF/resources
, /resources
, /static
, /public
or /templates
will not trigger a restart but will trigger a live reload. If you want to customize these exclusions you can use the spring.devtools.restart.exclude
property. For example, to exclude only /static
and /public
you would set the following:
某些资源当它们改变时不一定需要触发重启。例如,Thymeleaf模板可以就地编辑。默认情况下,/META-INF/maven
,/META-INF/resources
,/resources
,/static
,/public
或/templates
中资源的改变不会触发重启,但会触发实时重载。如果你想定制这些排除项,你可以使用spring.devtools.restart.exclude
属性。例如,仅排除/static
和/public
,设置如下:
1 | spring.devtools.restart.exclude=static/**,public/** |
If you want to keep those defaults and add additional exclusions, use the
spring.devtools.restart.additional-exclude
property instead.
如果你想保持这些默认,添加额外的排除项,可以使用
spring.devtools.restart.additional-exclude
属性。
20.2.2 Watching additional paths
You may want your application to be restarted or reloaded when you make changes to files that are not on the classpath. To do so, use the spring.devtools.restart.additional-paths
property to configure additional paths to watch for changes. You can use the spring.devtools.restart.exclude
property described above to control whether changes beneath the additional paths will trigger a full restart or just a live reload.
当你修改不在classpath
中的文件时,你可能也想重启或重载你的应用。为了这样做,可以使用spring.devtools.restart.additional-paths
属性来监控其它路径上的变化。你可以使用前面描述的spring.devtools.restart.exclude
属性来控制其它路径上的变化是否会触发重启或仅触发实时重载。
20.2.3 Disabling restart
If you don’t want to use the restart feature you can disable it using the spring.devtools.restart.enabled
property. In most cases you can set this in your application.properties
(this will still initialize the restart classloader but it won’t watch for file changes).
如果你想使用重启功能你可以通过spring.devtools.restart.enabled
属性禁用它。大多数情况下你可以在你的application.properties
中设置它(这仍会初始化重启类加载器但它不会监控文件的变化)。
If you need to completely disable restart support, for example, because it doesn’t work with a specific library, you need to set a System
property before calling SpringApplication.run(…)
. For example:
如果你需要完整的禁用重启支持,例如,因为它不能与一个特定的库一起工作,你需要在调用SpringApplication.run(…)
之前设置一个System
属性。例如:
1 | public static void main(String[] args) { |
20.2.4 Using a trigger file
If you work with an IDE that continuously compiles changed files, you might prefer to trigger restarts only at specific times. To do this you can use a “trigger file”, which is a special file that must be modified when you want to actually trigger a restart check. Changing the file only triggers the check and the restart will only occur if Devtools has detected it has to do something. The trigger file could be updated manually, or via an IDE plugin.
如果你的IDE可以持续编译变化的文件,你可以只在特定的时间触发重启。为了实现这个功能你可以使用『触发器文件』,当你需要真正触发重启检查时,它是一个你必须要修改文件。修改这个文件只触发重启检查,只有Devtools
检测到它必须要做些事情时,重启才会发生。触发器文件应该进行手动更新,或通过IDE插件更新。
To use a trigger file use the spring.devtools.restart.trigger-file
property.
为了使用触发器文件需要使用spring.devtools.restart.trigger-file
属性。
You might want to set
spring.devtools.restart.trigger-file
as a global setting so that all your projects behave in the same way.
为了使你所有的工程都表现一样,你需要将
spring.devtools.restart.trigger-file
设置为全局设置。
20.2.5 Customizing the restart classloader
As described in the Restart vs Reload section above, restart functionality is implemented by using two classloaders. For most applications this approach works well, however, sometimes it can cause classloading issues.
像前面的的Restart vs Reload
部分所讲的那样,重启功能是通过两个类加载器实现的。对于大多数应用来说这个方法能很好的工作,但是有时候它也会引起一些类加载问题。
By default, any open project in your IDE will be loaded using the “restart” classloader, and any regular .jar
file will be loaded using the “base” classloader. If you work on a multi-module project, and not each module is imported into your IDE, you may need to customize things. To do this you can create a META-INF/spring-devtools.properties
file.
默认情况下,IDE中的任何开放的工程都会使用“restart”类加载器进行加载,任何规范的.jar
文件都会使用“base”类加载器进行加载。如果你在一个多模块工程中工作,不是每一个模块都导入到你的IDE中,你可能需要定制一些东西。为了实现这个功能你可以创建一个META-INF/spring-devtools.properties
文件。
The spring-devtools.properties
file can contain restart.exclude.
and restart.include.
prefixed properties. The include
elements are items that should be pulled up into the “restart” classloader, and the exclude
elements are items that should be pushed down into the “base” classloader. The value of the property is a regex pattern that will be applied to the classpath.
spring-devtools.properties
可以包含restart.exclude.
和restart.include.
前缀属性。include
元素应该拉进“restart”类加载器中,exclude
元素应该推入到“base”类加载器中。属性值是应用到classpath
中的一个正则表达式。
For example:
例如:
1 | restart.exclude.companycommonlibs=/mycorp-common-[\\w-]+\.jar |
All property keys must be unique. As long as a property starts with
restart.include.
orrestart.exclude
. it will be considered.
所有属性的键必须是唯一的。只要
restart.include.
或restart.exclude
作为一个属性启动,它就被应用。All
META-INF/spring-devtools.properties
from the classpath will be loaded. You can package files inside your project, or in the libraries that the project consumes.
classpath
中的所有META-INF/spring-devtools.properties
都会被加载。你可以将文件打包进你的工程中,或这个工程使用的库中。
20.2.6 Known limitations
Restart functionality does not work well with objects that are deserialized using a standard ObjectInputStream
. If you need to deserialize data, you may need to use Spring’s ConfigurableObjectInputStream
in combination with Thread.currentThread().getContextClassLoader()
.
当存在使用标准ObjectInputStream
进行反序列化的对象时,重启功能不能很好的工作。如果你需要反序列化数据,你可能需要使用Spring的ConfigurableObjectInputStream
和Thread.currentThread().getContextClassLoader()
。
Unfortunately, several third-party libraries deserialize without considering the context classloader. If you find such a problem, you will need to request a fix with the original authors.
遗憾的是,一些第三方库反序列化时没有考虑上下文类加载器。如果你发现了这样的问题,你需要请求原作者进行修正。
20.3 LiveReload
The spring-boot-devtools
module includes an embedded LiveReload server that can be used to trigger a browser refresh when a resource is changed. LiveReload browser extensions are freely available for Chrome, Firefox and Safari from livereload.com.
spring-boot-devtools
模块包含一个内嵌的实时重载服务器,当资源改变时可以用来触发浏览器重新刷新。实时重载浏览器扩展对于livereload.com中的Chrome,Firefox和Safari而言是可用的。
If you don’t want to start the LiveReload server when your application runs you can set the spring.devtools.livereload.enabled
property to false
.
当你的应用运行时,如果你不想启动实时重载服务器,你可以将spring.devtools.livereload.enabled
属性设为false
。
You can only run one LiveReload server at a time. Before starting your application, ensure that no other LiveReload servers are running. If you start multiple applications from your IDE, only the first will have LiveReload support.
一次你只可以运行一个实时重载服务器。在启动你的应用之前,确保没有其它的实时重载服务器在运行。如果你从你的IDE中启动多个应用,只有第一个应用有实时重载服务器支持。
20.4 Global settings
You can configure global devtools settings by adding a file named .spring-boot-devtools.properties
to your $HOME
folder (note that the filename starts with “.”). Any properties added to this file will apply to all Spring Boot applications on your machine that use devtools. For example, to configure restart to always use a trigger file, you would add the following:
通过添加一个名为.spring-boot-devtools.properties
的文件到你的$HOME
文件夹中(注意文件名以.
开头),你可以配置全局开发者工具设置。任何添加到这个文件的属性都将应用到你机器上所有使用开发者工具的Spring Boot应用中。例如,为了配置重启时总是使用一个触发器文件,你需要添加如下内容:
~/.spring-boot-devtools.properties.
1 | spring.devtools.reload.trigger-file=.reloadtrigger |
20.5 Remote applications
The Spring Boot developer tools are not just limited to local development. You can also use several features when running applications remotely. Remote support is opt-in, to enable it you need to make sure that devtools
is included in the repackaged archive:
Spring Boot开发者工具是不受本地环境限制的,在运行远程应用时你也可以使用一些功能。远程支持是选择性加入的,为了使它起作用你需要确保devtools
包含在再打包的文件中:
1 | <build> |
Then you need to set a spring.devtools.remote.secret
property, for example:
然后你需要设置spring.devtools.remote.secret
属性,例如:
1 | spring.devtools.remote.secret=mysecret |
Enabling
spring-boot-devtools
on a remote application is a security risk. You should never enable support on a production deployment.
使
spring-boot-devtools
在远程应用上起作用是有安全风险的。在产品部署时,你不应该让它支持spring-boot-devtools
。
Remote devtools support is provided in two parts; there is a server side endpoint that accepts connections, and a client application that you run in your IDE. The server component is automatically enabled when the spring.devtools.remote.secret
property is set. The client component must be launched manually.
远程devtools
需要两部分提供支持:一个接收连接的服务器端,一个运行在IDE中的客户端应用。当设置spring.devtools.remote.secret
属性时,服务器组件会自动起作用。客户端组件必须手动启动。
20.5.1 Running the remote client application
The remote client application is designed to be run from within you IDE. You need to run org.springframework.boot.devtools.RemoteSpringApplication
using the same classpath as the remote project that you’re connecting to. The non-option argument passed to the application should be the remote URL that you are connecting to.
远程客户端应用设计要在你的IDE中运行。你需要运行org.springframework.boot.devtools.RemoteSpringApplication
,与要连接的远程工程要使用同样的classpath。传给应用的非可选参数应该是你要连接的远程URL。
For example, if you are using Eclipse or STS, and you have a project named my-app
that you’ve deployed to Cloud Foundry, you would do the following:
Select
Run Configurations…
from theRun
menu.Create a new
Java Application
“launch configuration”.Browse for the
my-app
project.Use
org.springframework.boot.devtools.RemoteSpringApplication
as the main class.Add
https://myapp.cfapps.io
to theProgram arguments
(or whatever your remote URL is).
例如,如果你在使用Eclipse或STS,你有一个名为my-app
的工程,它已经部署到了云计算中,你需要按照下面的步骤去做:
从
Run
菜单中选择Run Configurations…
。创建一个新的
Java Application
“launch configuration”。浏览
my-app
工程。使用
org.springframework.boot.devtools.RemoteSpringApplication
作为主类。添加
https://myapp.cfapps.io
到Program arguments
(或无论你的远程URL是什么)。
A running remote client will look like this:
一个运行的远程客户端如下:
1 | . ____ _ __ _ _ |
Because the remote client is using the same classpath as the real application it can directly read application properties. This is how the
spring.devtools.remote.secret
property is read and passed to the server for authentication.
因为远程客户端与真实的应用使用的
classpath
相同,因此它可以直接读取应用属性。这就是spring.devtools.remote.secret
属性是怎样读取并传递给服务器进行授权的。
It’s always advisable to use
https://
as the connection protocol so that traffic is encrypted and passwords cannot be intercepted.
为了传输可以加密,密码不能被解析,建议总是使用
https://
作为连接协议。
If you need to use a proxy to access the remote application, configure the
spring.devtools.remote.proxy.host
andspring.devtools.remote.proxy.port
properties.
如果你需要使用代理访问远程应用,配置
spring.devtools.remote.proxy.host
和spring.devtools.remote.proxy.port
属性。
20.5.2 Remote update
The remote client will monitor your application classpath for changes in the same way as the local restart. Any updated resource will be pushed to the remote application and (if required) trigger a restart. This can be quite helpful if you are iterating on a feature that uses a cloud service that you don’t have locally. Generally remote updates and restarts are much quicker than a full rebuild and deploy cycle.
远程客户端会像本地重启那样监控你应用的classpath
的变化。任何资源的更新都会推送到远程应用并(如果需要的话)触发重启。如果你在迭代一个本地没有的使用云服务的功能,它是非常有帮助的。通常更新和重启比整个重新构建部署更快。
Files are only monitored when the remote client is running. If you change a file before starting the remote client, it won’t be pushed to the remote server.
当远程客户端运行时只监控文件。如果在启动远程客户端之前你修改了文件,它将不会推送到远程服务器。
20.5.3 Remote debug tunnel
Java remote debugging is useful when diagnosing issues on a remote application. Unfortunately, it’s not always possible to enable remote debugging when your application is deployed outside of your data center. Remote debugging can also be tricky to setup if you are using a container based technology such as Docker.
当在远程应用上分析问题时,Java远程调试是非常有用的。遗憾的是,当你的应用部署离开你的数据中心时,远程调试并不总是能用的。如果你正在使用一个基于容器的技术例如Docker,要设置远程调试也是非常棘手的。
To help work around these limitations, devtools supports tunneling of remote debug traffic over HTTP. The remote client provides a local server on port 8000
that you can attach a remote debugger to. Once a connection is established, debug traffic is sent over HTTP to the remote application. You can use the spring.devtools.remote.debug.local-port
property if you want to use a different port.
为了帮助解决这些限制,devtools
支持在HTTP协议上的远程调试通道。远程客户端提供一个端口为8000
的本地服务器,你可以在这上面添加一个远程调试器。一旦建立了连接,调试通道将会在HTTP上发送到远程应用上。如果你想使用一个不同的端口,你可以使用spring.devtools.remote.debug.local-port
属性。
You’ll need to ensure that your remote application is started with remote debugging enabled. Often this can be achieved by configuring JAVA_OPTS
. For example, with Cloud Foundry you can add the following to your manifest.yml
:
你需要确保你的远程应用启动了并且远程调试可用。这经常可以通过配置JAVA_OPTS
来完成。例如,在云计算平台你可以添加下面的内容到你的manifest.yml
中:
1 | --- |
Notice that you don’t need to pass an
address=NNNN
option to-Xrunjdwp
. If omitted Java will simply pick a random free port.
注意你不必向
-Xrunjdwp
传递address=NNNN
选择。如果被忽略Java将会简单的选择一个随机自由的端口。
Debugging a remote service over the Internet can be slow and you might need to increase timeouts in your IDE. For example, in Eclipse you can select
Java → Debug
fromPreferences…
and change theDebugger timeout (ms)
to a more suitable value (60000
works well in most situations).
在网上调试一个远程服务可能是非常慢的,你可能需要在你的IDE中添加
timeouts
。例如,在Eclipse中你可以从Preferences…
选择Java → Debug
,并将Debugger timeout (ms)
改成更合适的值(60000
在大多数情况下都能很好工作)。
21. Packaging your application for production
Executable jars can be used for production deployment. As they are self-contained, they are also ideally suited for cloud-based deployment.
可执行jars
可以用来进行产品部署。当它们是自包含时,理想情况下它们也是适合云部署的。
For additional “production ready” features, such as health, auditing and metric REST or JMX end-points; consider adding spring-boot-actuator
. See Part V, “Spring Boot Actuator: Production-ready features” for details.
对于其它的“production ready”功能,例如健康,审计和度量REST或JMX端点;考虑添加spring-boot-actuator
。更多细节请看第五部分,“Spring Boot Actuator: Production-ready features”。
22. What to read next
You should now have good understanding of how you can use Spring Boot along with some best practices that you should follow. You can now go on to learn about specific Spring Boot features in depth, or you could skip ahead and read about the “production ready” aspects of Spring Boot.
现在你应该对怎么使用Spring Boot以及应该循序的一些最佳实践有了很好的理解。你可以继续学习关于Spring Boot的一些深度功能,或者你可以跳过前面,直接阅读Spring Boot “production ready”方面的内容。
Part IV. Spring Boot features
This section dives into the details of Spring Boot. Here you can learn about the key features that you will want to use and customize. If you haven’t already, you might want to read the Part II, “Getting started” and Part III, “Using Spring Boot” sections so that you have a good grounding of the basics.
这一部分进入Spring Boot细节部分。在这部分你会了解到你想使用和定制的一些重要特性。如果你还没准备好,你可以阅读第二部分“Getting started”和第三部分“Using Spring Boot”,可以对基础知识有个较好的认识。
23. SpringApplication
The SpringApplication
class provides a convenient way to bootstrap a Spring application that will be started from a main()
method. In many situations you can just delegate to the static SpringApplication.run
method:
SpringApplication
提供了一种很方便的方式来引导Spring应用,Spring应用可以从main()
方法中启动。许多情况下你可以委托给静态方法SpringApplication.run
:
1 | public static void main(String[] args) { |
When your application starts you should see something similar to the following:
当你的应用启动时你应该看到类似于下面的东西:
1 | . ____ _ __ _ _ |
By default INFO
logging messages will be shown, including some relevant startup details such as the user that launched the application.
默认情况下会输出INFO
日志信息,包括一些相关的启动细节例如启动应用的用户。
23.1 Startup failure
If your application fails to start, registered FailureAnalyzers
get a chance to provide a dedicated error message and a concrete action to fix the problem. For instance if you start a web application on port 8080
and that port is already in use, you should see something similar to the following:
如果你的应用启动失败,注册FailureAnalyzers
有可能会提供专门的错误信息和解决这个问题的具体行动。例如,如果你启动一个8080
端口的web应用并且这个端口已经被占用,你应该会看到类似于下面的内容:
1 | *************************** |
Spring Boot provides numerous
FailureAnalyzer
implementations and you can add your own very easily.
Spring Boot提供了许多
FailureAnalyzer
实现,你可以很容易添加自己的FailureAnalyzer
实现。
If no failure analyzers are able to handle the exception, you can still display the full auto-configuration report to better understand what went wrong. To do so you need to enable the debug
property or enable DEBUG
logging for org.springframework.boot.autoconfigure.logging.AutoConfigurationReportLoggingInitializer
.
如果没有失败分析器能处理这个异常,你仍可以显示完整的自动配置报告,从而更好的理解什么地方出问题了。为了实现这个你需要启用debug
属性或启用org.springframework.boot.autoconfigure.logging.AutoConfigurationReportLoggingInitializer
的DEBUG
日志。
For instance, if you are running your application using java -jar
you can enable the debug
property as follows:
例如,如果你使用java -jar
运行应用,你可以用下面的形式启用debug
属性:
1 | $ java -jar myproject-0.0.1-SNAPSHOT.jar --debug |
23.2 Customizing the Banner
The banner that is printed on start up can be changed by adding a banner.txt
file to your classpath, or by setting banner.location
to the location of such a file. If the file has an unusual encoding you can set banner.charset
(default is UTF-8
). In addition to a text file, you can also add a banner.gif
, banner.jpg
or banner.png
image file to your classpath, or set a banner.image.location
property. Images will be converted into an ASCII art representation and printed above any text banner.
启动时打印的标语可以通过在classpath中添加一个banner.txt
文件或者将banner.location
设置为banner.txt
文件的位置来修改。如果文件是一种不常见的编码方式,你可以设置banner.charset
(默认是UTF-8
)。除了文本文件之外,你也添加一个banner.gif
,banner.jpg
或banner.png
图像文件到classpath中,或者设置一个banner.image.location
属性。图像将被转换成ASCII艺术表示并打印在文本标语之上。
Inside your banner.txt
file you can use any of the following placeholders:
在banner.txt
内部你可以使用下面的任何占位符:
Table 23.1. Banner variables
Variable | Description |
---|---|
${application.version} | The version number of your application as declared in MANIFEST.MF . For example Implementation-Version: 1.0 is printed as 1.0 . |
${application.formatted-version} | The version number of your application as declared in MANIFEST.MF formatted for display (surrounded with brackets and prefixed with v ). For example (v1.0 ). |
${spring-boot.version} | The Spring Boot version that you are using. For example 1.4.2.RELEASE . |
${spring-boot.formatted-version} | The Spring Boot version that you are using formatted for display (surrounded with brackets and prefixed with v ). For example (v1.4.2.RELEASE ). |
${Ansi.NAME} (or ${AnsiColor.NAME}, ${AnsiBackground.NAME}, ${AnsiStyle.NAME}) | Where NAME is the name of an ANSI escape code. See AnsiPropertySource for details. |
${application.title} | The title of your application as declared in MANIFEST.MF . For example Implementation-Title: MyApp is printed as MyApp . |
Table 23.1. Banner变量
Variable | Description |
---|---|
${application.version} | 你的应用的版本号在MANIFEST.MF 中声明。 例如Implementation-Version: 1.0 打印成1.0 . |
${application.formatted-version} | 在MANIFEST.MF 中的声明的应用版本号进行格式化显示(加上前缀v 并用括号包裹)。例如(v1.0) 。 |
${spring-boot.version} | 你使用的Spring Boot版本。例如1.4.2.RELEASE . |
${spring-boot.formatted-version} | 你使用的Spring Boot版本进行格式化显示加上前缀v 并用括号包裹)。例如(v1.4.2.RELEASE) 。 |
${Ansi.NAME} (or ${AnsiColor.NAME}, ${AnsiBackground.NAME}, ${AnsiStyle.NAME}) | NAME 是ANSI转义码的名字。更多细节请看AnsiPropertySource 。 |
${application.title} | 在MANIFEST.MF 中声明的应用标题。例如Implementation-Title: MyApp 打印成MyApp . |
The
SpringApplication.setBanner(…)
method can be used if you want to generate a banner programmatically. Use theorg.springframework.boot.Banner
interface and implement your ownprintBanner()
method.
如果你想自动生成一个标语你可以使用
SpringApplication.setBanner(…)
方法。使用org.springframework.boot.Banner
接口并实现你自己的printBanner()
方法。
You can also use the spring.main.banner-mode
property to determine if the banner has to be printed on (console), using the configured logger (log) or not at all (off).
你也可以使用spring.main.banner-mode
属性来决定标语是否必须在System.out
(控制台)上输出,使用配置的日志(log)或一点也不用(off)。
The printed banner will be registered as a singleton bean under the name pringBootBanner
.
输出的banner会注册名字为pringBootBanner
的单例bean。
YAML maps
off
tofalse
so make sure to add quotes if you want to disable the banner in your application.
1
2
3 spring:
main:
banner-mode: "off"
如果你想在你的应用中禁用banner,YAML会将
off
映射为false
,因此要确保添加引用。
1
2
3 spring:
main:
banner-mode: "off"
23.3 Customizing SpringApplication
If the SpringApplication
defaults aren’t to your taste you can instead create a local instance and customize it. For example, to turn off the banner you would write:
如果你不喜欢默认的SpringApplication
,你可以创建一个本地实例并定制它。例如,关闭你写的banner:
1 | public static void main(String[] args) { |
The constructor arguments passed to
SpringApplication
are configuration sources for spring beans. In most cases these will be references to@Configuration
classes, but they could also be references to XML configuration or to packages that should be scanned.
传给
SpringApplication
的构造函数参数是Spring beans配置源。在大多数情况下将会引用@Configuration
类,但它们也可以引用XML配置或应该扫描的包。
It is also possible to configure the SpringApplication
using an application.properties
file. See Chapter 24, Externalized Configuration for details.
也可以使用application.properties
文件配置SpringApplication
。更多细节请看24章,『外部配置』。
For a complete list of the configuration options, see the SpringApplication
Javadoc.
完整的配置选项列表,请看SpringApplication
文档。
23.4 Fluent builder API
If you need to build an ApplicationContext
hierarchy (multiple contexts with a parent/child relationship), or if you just prefer using a fluent
builder API, you can use the SpringApplicationBuilder
.
如果你需要构建ApplicationContext
分层(多个具有父/子关系的上下文),或者你更喜欢使用fluent
的构建器API,你可以使用SpringApplicationBuilder
。
The SpringApplicationBuilder
allows you to chain together multiple method calls, and includes parent
and child
methods that allow you to create a hierarchy.
SpringApplicationBuilder
允许你链接多个方法调用,包括允许你创建分层的parent
和child
方法。
For example:
例如:
1 | new SpringApplicationBuilder() |
There are some restrictions when creating an
ApplicationContext
hierarchy, e.g. Web components must be contained within the child context, and the sameEnvironment
will be used for both parent and child contexts. See theSpringApplicationBuilder
Javadoc for full details.
当创建
ApplicationContext
分层时有一些限制,例如,子上下文必须包含web组件,父子上下文将使用同一个Environment
。更完整的细节请看SpringApplicationBuilder
文档。
23.5 Application events and listeners
In addition to the usual Spring Framework events, such as ContextRefreshedEvent
, a SpringApplication
sends some additional application events.
除了平常的Spring框架事件之外,例如ContextRefreshedEvent
,SpringApplication
会发送一些其它的应用事件。
Some events are actually triggered before the
ApplicationContext
is created so you cannot register a listener on those as a@Bean
. You can register them via theSpringApplication.addListeners(…)
orSpringApplicationBuilder.listeners(…)
methods.If you want those listeners to be registered automatically regardless of the way the application is created you can add a
META-INF/spring.factories
file to your project and reference your listener(s) using theorg.springframework.context.ApplicationListener
key.
1 org.springframework.context.ApplicationListener=com.example.project.MyListener
在
ApplicationContext
创建之前实际上会触发一些事件,因此你不能使用@Bean
来注册这些监听器。你可以通过SpringApplication.addListeners(…)
或SpringApplicationBuilder.listeners(…)
方法来注册这些监听器。如果你想自动注册这些监听器,不管上下文的创建方式,你可以在你的工程中添加
META-INF/spring.factories
文件,并通过org.springframework.context.ApplicationListener
作为key来引用你的监听器。
1 org.springframework.context.ApplicationListener=com.example.project.MyListener
Application events are sent in the following order, as your application runs:
- An
ApplicationStartedEvent
, but before any processing except the registration of listeners and initializers. - An
ApplicationEnvironmentPreparedEvent
is sent when theEnvironment
to be used in the context is known, but before the context is created. - An
ApplicationPreparedEvent
is sent just before the refresh is started, but after bean definitions have been loaded. - An
ApplicationReadyEvent
is sent after the refresh and any related callbacks have been processed to indicate the application is ready to service requests. - An
ApplicationFailedEvent
is sent if there is an exception on startup.
当你的应用运行时,应用事件以下面的顺序发送:
- 在运行启动时发送
ApplicationStartedEvent
,除了监听器和初始化器注册之外,在进行任何处理之前发送。 - 当在上下文中使用的
Environment
已知时,发送ApplicationEnvironmentPreparedEvent
,但发送是在上下文创建之前。 - 在再刷新启动之前,但在bean定义加载之后,发送
ApplicationPreparedEvent
。 - 在再刷新之后,发送
ApplicationReadyEvent
,任何相关的回调函数都处理完成之后,意味着应用已经准备处理服务请求了。 - 如果启动时出现异常,发送
ApplicationFailedEvent
.
You often won’t need to use application events, but it can be handy to know that they exist. Internally, Spring Boot uses events to handle a variety of tasks.
经常你不需要使用应用事件,但知道它们的存在是便利的。Spring Boot内部使用事件来处理大量的任务。
23.6 Web environment
A SpringApplication
will attempt to create the right type of ApplicationContext
on your behalf. By default, an AnnotationConfigApplicationContext
or AnnotationConfigEmbeddedWebApplicationContext
will be used, depending on whether you are developing a web application or not.
SpringApplication
会尝试创建代表你的合适的ApplicationContext
类型。默认情况下,会使用AnnotationConfigApplicationContext
或AnnotationConfigEmbeddedWebApplicationContext
,依赖于你是否在开发一个web应用。
The algorithm used to determine a ‘web environment’ is fairly simplistic (based on the presence of a few classes). You can use setWebEnvironment(boolean webEnvironment)
if you need to override the default.
使用的决定web environment
的算法是相对简单的(基于现有的一些类)。如果你需要覆写默认值你可以使用setWebEnvironment(boolean webEnvironment)
。
It is also possible to take complete control of the ApplicationContext
type that will be used by calling setApplicationContextClass(…)
.
完全控制ApplicationContext
类型也是可能的,通过调用setApplicationContextClass(…)
使用。
It is often desirable to call
setWebEnvironment(false)
when usingSpringApplication
within a JUnit test.
当在JUnit测试时使用
SpringApplication
,经常需要调用setWebEnvironment(false)
。
23.7 Accessing application arguments
If you need to access the application arguments that were passed to SpringApplication.run(…)
you can inject a org.springframework.boot.ApplicationArguments
bean. The ApplicationArguments
interface provides access to both the raw String[]
arguments as well as parsed option
and non-option
arguments:
如果你需要访问传进SpringApplication.run(…)
中的应用参数,你可以注入org.springframework.boot.ApplicationArguments
bean。ApplicationArguments
接口提供了访问原始String[]
和转换的option
,non-option
参数。
1 | import org.springframework.boot.* |
Spring Boot will also register a
CommandLinePropertySource
with the SpringEnvironment
. This allows you to also inject single application arguments using the@Value
annotation.
Spring Boot也在Spring
Environment
中注册CommandLinePropertySource
。这也允许你使用@Value
注解注入单个应对参数。
23.8 Using the ApplicationRunner or CommandLineRunner
If you need to run some specific code once the SpringApplication
has started, you can implement the ApplicationRunner
or CommandLineRunner
interfaces. Both interfaces work in the same way and offer a single run
method which will be called just before SpringApplication.run(…)
completes.
如果你需要在SpringApplication
启动时运行一些特定的代码,你可以实现ApplicationRunner
或CommandLineRunner
接口。这两个接口以同样方式工作,并有一个单独的run
方法,在SpringApplication.run(…)
之前会调用这个run
方法。
The CommandLineRunner
interfaces provides access to application arguments as a simple string array, whereas the ApplicationRunner
uses the ApplicationArguments
interface discussed above.
CommandLineRunner
接口提供了对应用参数的访问,应用参数作为一个简单的字符串数组,而ApplicationRunner
使用前面描述的ApplicationArguments
接口。
1 | import org.springframework.boot.* |
You can additionally implement the org.springframework.core.Ordered
interface or use the org.springframework.core.annotation.Order
annotation if several CommandLineRunner
or ApplicationRunner
beans are defined that must be called in a specific order.
另外,如果定义的CommandLineRunner
或ApplicationRunner
beans必须以指定顺序调用,你可以实现org.springframework.core.Ordered
接口或org.springframework.core.annotation.Order
注解。
23.9 Application exit
Each SpringApplication
will register a shutdown hook with the JVM to ensure that the ApplicationContext
is closed gracefully on exit. All the standard Spring lifecycle callbacks (such as the DisposableBean
interface, or the @PreDestroy
annotation) can be used.
为了确保ApplicationContext
在关闭时安全退出, 每个SpringApplication
都会在JVM中注册一个关闭钩子。所有的标准Spring生命周期回调函数(例如DisposableBean
接口,或@PreDestroy
注解)都会被使用。
In addition, beans may implement the org.springframework.boot.ExitCodeGenerator
interface if they wish to return a specific exit code when the application ends.
另外,当应用退出时,如果想返回一个指定的退出码,beans可以实现org.springframework.boot.ExitCodeGenerator
接口。
23.10 Admin features
It is possible to enable admin-related features for the application by specifying the spring.application.admin.enabled
property. This exposes the SpringApplicationAdminMXBean
on the platform MBeanServer
. You could use this feature to administer your Spring Boot application remotely. This could also be useful for any service wrapper implementation.
如果应用想启用admin相关的功能,可以指定spring.application.admin.enabled
属性。这会在平台MBeanServer
上暴露SpringApplicationAdminMXBean
。你可以使用这个功能远程的管理你的Spring Boot应用。对于任何服务包裹的实现这是很有用的。
If you want to know on which HTTP port the application is running, get the property with key
local.server.port
.
如果你想知道应用运行的HTTP接口,通过关键字
local.server.port
可以得到这个属性。
Take care when enabling this feature as the MBean exposes a method to shutdown the application.
当启用这个功能时要非常小心,因为MBean会暴露一个关闭应用的方法。
24. Externalized Configuration
Spring Boot allows you to externalize your configuration so you can work with the same application code in different environments. You can use properties files, YAML files, environment variables and command-line arguments to externalize configuration. Property values can be injected directly into your beans using the @Value
annotation, accessed via Spring’s Environment
abstraction or bound to structured objects via @ConfigurationProperties
.
Spring Boot允许你进行外部化配置,因此可以将同样的应用代码在不同的环境中运行。你可以使用属性文件,YAML文件,环境变量和命令行参数来进行外部化配置。属性值可以使用@Value
注解直接注入到你的beans中,通过Spring的Environment
抽象或通过@ConfigurationProperties
绑定到结构化对象上来访问。
Spring Boot uses a very particular PropertySource
order that is designed to allow sensible overriding of values. Properties are considered in the following order:
Spring Boot使用非常特别的PropertySource
顺序,这个顺序的设计是为了允许值的合理重写。属性被认为是按照以下顺序:
- Devtools global settings properties on your home directory (
~/.spring-boot-devtools.properties
when devtools is active). @TestPropertySource
annotations on your tests.@SpringBootTest#properties
annotation attribute on your tests.- Command line arguments.
- Properties from
SPRING_APPLICATION_JSON
(inline JSON embedded in an environment variable or system property) ServletConfig
init parameters.ServletContext
init parameters.- JNDI attributes from
java:comp/env
. - Java System properties (
System.getProperties()
). - OS environment variables.
- A
RandomValuePropertySource
that only has properties inrandom.*
. - Profile-specific application properties outside of your packaged jar (
application-{profile}.properties
and YAML variants) - Profile-specific application properties packaged inside your jar (
application-{profile}.properties
and YAML variants) - Application properties outside of your packaged jar (
application.properties
and YAML variants). - Application properties packaged inside your jar (
application.properties
and YAML variants). @PropertySource
annotations on your@Configuration
classes.Default properties (specified using
SpringApplication.setDefaultProperties
).根目录下的开发工具全局设置属性(当开发工具激活时为
~/.spring-boot-devtools.properties
)。- 测试中的
@TestPropertySource
注解。 - 测试中的
@SpringBootTest#properties
注解特性。 - 命令行参数。
SPRING_APPLICATION_JSON
中的属性(环境变量或系统属性中的内联JSON嵌入)。ServletConfig
初始化参数。ServletContext
初始化参数。java:comp/env
的JNDI特性。- Java系统属性 (
System.getProperties()
)。 - 操作系统环境变量。
RandomValuePropertySource
只在random.*
中有属性。- jar包之外的指定配置文件的应用属性(
application-{profile}.properties
和YAML变量)。 - jar包之内的指定配置文件的应用属性(
application-{profile}.properties
和YAML变量)。 - jar包之外的应用属性 (
application.properties
和YAML变量)。 - jar包之内的应用属性 (
application.properties
和YAML变量)。 @Configuration
类中的@PropertySource
注解 。- 默认属性(通过
SpringApplication.setDefaultProperties
指定).
To provide a concrete example, suppose you develop a @Component
that uses a name
property:
为了提供一个具体的例子,假设你开发了一个使用name
属性的@Component
:
1 | import org.springframework.stereotype.* |
On your application classpath (e.g. inside your jar) you can have an application.properties
that provides a sensible default property value for name
. When running in a new environment, an application.properties
can be provided outside of your jar that overrides the name
; and for one-off testing, you can launch with a specific command line switch (e.g. java -jar app.jar --name="Spring"
).
在你的应用路径中(例如在你的jar内部),你可以使用application.properties
为name
提供一个合理的默认属性值。当在新环境运行时,application.properties
可以在jar外部提供来重写name
;对于一次性测试,你可以通过指定的命令行切换来启动(例如java -jar app.jar --name="Spring"
)。
The
SPRING_APPLICATION_JSON
properties can be supplied on the command line with an environment variable. For example in a UN*X shell:
1 $ SPRING_APPLICATION_JSON='{"foo":{"bar":"spam"}}' java -jar myapp.jarIn this example you will end up with
foo.bar=spam
in the SpringEnvironment
. You can also supply the JSON asspring.application.json
in a System variable:
1 $ java -Dspring.application.json='{"foo":"bar"}' -jar myapp.jar
or command line argument:1
$ java -jar myapp.jar --spring.application.json='{"foo":"bar"}'
or as a JNDI variable
java:comp/env/spring.application.json
.
SPRING_APPLICATION_JSON
可以在命令行中通过环境变量提供。例如在UNIX shell中:
1 $ SPRING_APPLICATION_JSON='{"foo":{"bar":"spam"}}' java -jar myapp.jar在这个例子中,Spring的
Environment
中会有foo.bar=spam
。你也可以在系统变量中提供JSON作为spring.application.json
。
1 $ java -Dspring.application.json='{"foo":"bar"}' -jar myapp.jar或命令行参数:
1 $ java -jar myapp.jar --spring.application.json='{"foo":"bar"}'或JNDI变量
java:comp/env/spring.application.json
24.1 Configuring random values
The RandomValuePropertySource
is useful for injecting random values (e.g. into secrets or test cases). It can produce integers, longs, uuids or strings, e.g.
当注入随机值时,RandomValuePropertySource
是很有用的(例如,注入秘密或测试用例)。它可以产生integers
,longs
,uuids
或strings
,例如:
1 | my.secret=${random.value} |
The random.int*
syntax is OPEN value (,max) CLOSE
where the OPEN,CLOSE
are any character and value,max
are integers. If max
is provided then value
is the minimum value and max
is the maximum (exclusive).
random.int*
语法OPEN value (,max) CLOSE
,OPEN,CLOSE
可以是任何字符,value,max
是整数。如果提供了max
,则value
是最小值,max
是最大值(不包含)。
24.2 Accessing command line properties
By default SpringApplication
will convert any command line option arguments (starting with ‘–’, e.g. --server.port=9000
) to a property
and add it to the Spring Environment
. As mentioned above, command line properties always take precedence over other property sources.
默认情况下,SpringApplication
会将任何命令行参数(以--
开头,例如--server.port=9000
)转换成property
并将其添加到Spring的Environment
中。正如前面提到的那样,命令行属性总是优先于其它的配置源。
If you don’t want command line properties to be added to the Environment
you can disable them using SpringApplication.setAddCommandLineProperties(false)
.
如果你想命令行属性添加到Environment
中,你可以使用SpringApplication.setAddCommandLineProperties(false)
禁用它。
24.3 Application property files
SpringApplication
will load properties from application.properties
files in the following locations and add them to the Spring Environment
:
- A
/config
subdirectory of the current directory. - The current directory
- A classpath
/config
package - The classpath root
SpringApplication
会从以下位置的application.properties
文件中加载属性并将它们添加到Spring的Environment
中:
当前目录的子目录
/config
当前目录
classpath中的
/config
包classpath的根目录
The list is ordered by precedence (properties defined in locations higher in the list override those defined in lower locations).
这个列表是按优先级排序的(在更高位置的属性会重写定义在更低位置的属性)。
You can also use YAML (‘.yml’) files as an alternative to ‘.properties’.
你也可以使用YAML(
.yml
)文件来代替.properties
文件。
If you don’t like application.properties
as the configuration file name you can switch to another by specifying a spring.config.name
environment property. You can also refer to an explicit location using the spring.config.location
environment property (comma-separated list of directory locations, or file paths).
如果你不喜欢用application.properties
作为配置文件的名字,你可以通过指定spring.config.name
环境属性来来改变配置文件的名字。你也可以使用spring.config.location
环境属性来引用一个显式的位置(目录位置或文件路径以逗号分隔)。
1 | $ java -jar myproject.jar --spring.config.name=myproject |
or
1 | $ java -jar myproject.jar --spring.config.location=classpath:/default.properties,classpath:/override.properties |
spring.config.name
andspring.config.location
are used very early to determine which files have to be loaded so they have to be defined as an environment property (typically OS env, system property or command line argument).
spring.config.name
和spring.config.location
可以在早期用来决定加载哪一个文件,因此必须被定义为环境属性(通常是操作系统环境,系统属性或命令行参数)。
If spring.config.location
contains directories (as opposed to files) they should end in /
(and will be appended with the names generated from spring.config.name
before being loaded, including profile-specific file names). Files specified in spring.config.location
are used as-is, with no support for profile-specific variants, and will be overridden by any profile-specific properties.
如果spring.config.location
包含目录(相对于文件而言),它们应该以/
结尾(在加载之前,在后面添加上从spring.config.name
中产生的名字,包括指定配置文件的名字)。在spring.config.location
中指定的文件按原样使用,不支持指定配置文件变量,将会被任何指定配置文件的属性覆盖。
The default search path classpath:,classpath:/config,file:,file:config/
is always used, irrespective of the value of spring.config.location
. This search path is ordered from lowest to highest precedence (file:config/
wins). If you do specify your own locations, they take precedence over all of the default locations and use the same lowest to highest precedence ordering. In that way you can set up default values for your application in application.properties
(or whatever other basename you choose with spring.config.name
) and override it at runtime with a different file, keeping the defaults.
默认搜索路径一直用classpath:,classpath:/config,file:,file:config/
,不管spring.config.location
中的值。搜索路径按从低到高排序(file:config/
最高)。如果你指定了自己的位置,它们优先于所有的默认位置并使用同样的从低到高的顺序。这样你可以在application.properties
中为你的应用设置默认值(或你可以选择spring.config.name
的其它生成文件基本名),在运行时用其它的文件覆盖它,同时保留默认值。
If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (e.g.
SPRING_CONFIG_NAME
instead ofspring.config.name
).
如果你使用环境变量而不是系统属性,大多数操作系统不允许句号分隔的关键字,但你可以用下划线代替(例如,
SPRING_CONFIG_NAME
代替spring.config.name
)。If you are running in a container then JNDI properties (in
java:comp/env
) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties.
如果你在容器中运行,那么JNDI属性(在
java:comp/env
中)或servlet上下文初始化参数也可以用来代替环境变量或系统属性。
24.4 Profile-specific properties
In addition to application.properties
files, profile-specific properties can also be defined using the naming convention application-{profile}.properties
. The Environment
has a set of default profiles (by default [default]
) which are used if no active profiles are set (i.e. if no profiles are explicitly activated then properties from application-default.properties
are loaded).
除了application.properties
文件之外,特定的profile属性也可以使用命名规范application-{profile}.properties
来定义。Environment
有一系列默认配置文件(默认为[default]
),如果没有设置激活的配置文件,会使用默认的配置文件(例如,如果没有激活显式的配置文件,则会加载application-default.properties
中的属性)。
Profile-specific properties are loaded from the same locations as standard application.properties
, with profile-specific files always overriding the non-specific ones irrespective of whether the profile-specific files are inside or outside your packaged jar.
特定的profile属性会从相同位置加载application.properties
,特定的profile文件总是覆盖非特定的配置文件,无论特定profile文件在你打包的jar内部还是外部。
If several profiles are specified, a last wins strategy applies. For example, profiles specified by the spring.profiles.active
property are added after those configured via the SpringApplication
API and therefore take precedence.
如果指定了几个配置文件,将会应用最后一个。例如,spring.profiles.active
属性指定的配置文件在那些配置的文件之后通过SpringApplication
API添加,因此优先级更高。
If you have specified any files in
spring.config.location
, profile-specific variants of those files will not be considered. Use directories inspring.config.location
if you also want to also use profile-specific properties.
如果你在
spring.config.location
中指定了任何文件,那些文件的特定profile版本将不会被考虑。如果你也想使用特定的profile属性,在spring.config.location
中使用目录。
24.5 Placeholders in properties
The values in application.properties
are filtered through the existing Environment
when they are used so you can refer back to previously defined values (e.g. from System properties).
当使用application.properties
中的值时,会通过现有的Environment
进行过滤,因此你可以参考前面定义的值(例如从系统属性中)。
1 | app.name=MyApp |
You can also use this technique to create ‘short’ variants of existing Spring Boot properties. See the Section 70.4, “Use ‘short’ command line arguments” how-to for details.
你也可以使用这个技术来创建现有的Spring Boot属性的
short
版本。怎样使用的更多细节请看70.4小节,“Use ‘short’ command line arguments”。
24.6 Using YAML instead of Properties
YAML is a superset of JSON, and as such is a very convenient format for specifying hierarchical configuration data. The SpringApplication
class will automatically support YAML as an alternative to properties whenever you have the SnakeYAML library on your classpath.
YAML是JSON的超集,它可以用一种非常方便的形式来指定分层配置数据。当你的类路径有SnakeYAML库时,SpringApplication
类自动支持YAML作为properties的一个替代品。
If you use ‘Starters’ SnakeYAML will be automatically provided via
spring-boot-starter
.
如果你使用‘Starters’,SnakeYAML将由
spring-boot-starter
自动提供。
24.6.1 Loading YAML
Spring Framework provides two convenient classes that can be used to load YAML documents. The YamlPropertiesFactoryBean
will load YAML as Properties
and the YamlMapFactoryBean
will load YAML as a Map
.
Spring框架提供了两个类用来方便的加载YAML文档。YamlPropertiesFactoryBean
将加载YAML作为Properties
,YamlMapFactoryBean
将加载YAML作为Map
。
For example, the following YAML document:
例如,下面的YAML文档:
1 | environments: |
Would be transformed into these properties:
将被转换成这些属性:
1 | environments.dev.url=http://dev.bar.com |
YAML lists are represented as property keys with [index]
dereferencers, for example this YAML:
YAML列表通过[index]
解引用表示为属性的key,例如这个YAML:
1 | my: |
Would be transformed into these properties:
将被转换成这些属性:
1 | my.servers[0]=dev.bar.com |
To bind to properties like that using the Spring DataBinder
utilities (which is what @ConfigurationProperties
does) you need to have a property in the target bean of type java.util.List
(or Set
) and you either need to provide a setter
, or initialize it with a mutable value, e.g. this will bind to the properties above:
为了像使用Spring的DataBinder
一样(@ConfigurationProperties
的功能)绑定这些属性,你需要在类型为java.util.List
(或Set
)的目标bean中有属性,你需要提供一个setter
或用一个可变的值来对它初始化,例如,绑定上面的属性值:
1 | @ConfigurationProperties(prefix="my") |
24.6.2 Exposing YAML as properties in the Spring Environment
The YamlPropertySourceLoader
class can be used to expose YAML as a PropertySource
in the Spring Environment
. This allows you to use the familiar @Value
annotation with placeholders syntax to access YAML properties.
YamlPropertySourceLoader
类可以在Spring的Environment
中将YAML作为PropertySource
。这允许你使用熟悉的@Value
注解和占位符语法来访问YAML属性。
24.6.3 Multi-profile YAML documents
You can specify multiple profile-specific YAML documents in a single file by using a spring.profiles
key to indicate when the document applies. For example:
你可以在单个文件中指定多个特定profile的YAML文档,当应用文档时,通过spring.profiles
关键字来表明使用哪个文档。例如:
1 | server: |
In the example above, the server.address
property will be 127.0.0.1
if the development
profile is active. If the development
and production
profiles are not enabled, then the value for the property will be 192.168.1.100
.
在上面的例子中,如果development
profile被激活,server.address
的值为127.0.0.1
。如果development
和production
profile不可用,server.address
的值为192.168.1.100
。
The default profiles are activated if none are explicitly active when the application context starts. So in this YAML we set a value for security.user.password
that is only available in the “default” profile:
当应用上下文启动时,如果没有显式的激活profile,则激活默认的profile。因此在这个YAML文件中我们仅在”default” profile中设置了security.user.password
。
1 | server: |
whereas in this example, the password is always set because it isn’t attached to any profile, and it would have to be explicitly reset in all other profiles as necessary:
在这个例子中,密码总是设置的,因为它没有添加到如何profile中,必要时我们必须在其它的profile中显式的对它重新设置:
1 | server: |
Spring profiles designated using the “spring.profiles” element may optionally be negated using the !
character. If both negated and non-negated profiles are specified for a single document, at least one non-negated profile must match and no negated profiles may match.
Spring profiles被设计为使用”spring.profiles”元素可以选择性的用!
字符进行否定。如果否定的和非否定的profile指向一个单独的文档,必须至少匹配一个非否定的profile,可能没有否定的profile进行匹配。
24.6.4 YAML shortcomings
YAML files can’t be loaded via the @PropertySource
annotation. So in the case that you need to load values that way, you need to use a properties file.
YAML文件不能通过@PropertySource
注解进行加载。因此在这种情况下如果你需要加载值,你需要使用属性文件。
24.6.5 Merging YAML lists
As we have seen above, any YAML content is ultimately transformed to properties. That process may be counter intuitive when overriding “list” properties via a profile.
正如我们上面看到的,任何YAML内容最终都要转换成属性。当通过profile重写“list“属性时,这个过程可能有违直觉。
For example, assume a MyPojo
object with name
and description
attributes that are null by default. Let’s expose a list of MyPojo
from FooProperties
:
例如,假设MyPojo
对象的name
和description
属性默认情况下为空。从FooProperties
公开一个MyPojo
列表:
1 | "foo") ( |
Consider the following configuration:
考虑下面的配置:
1 | foo: |
If the dev
profile isn’t active, FooProperties.list
will contain one MyPojo
entry as defined above. If the dev
profile is enabled however, the list
will still only contain one entry (with name “my another name” and description null). This configuration will not add a second MyPojo
instance to the list
, and it won’t merge the items.
如果dev
profile没有激活,FooProperties.list
将包含一个上面定义的MyPojo
输入。然而如果dev
profile可用,lists
仍只包含一个输入(name为“my another name”,description为空)。这个配置将不能添加第二个MyPojo
到list
中,并且它将不能合并这些项。
When a collection is specified in multiple profiles, the one with highest priority is used (and only that one):
当在多个profiles中指定一个集合时,将会使用最高优先级的那个集合(唯一的哪个):
1 | foo: |
In the example above, considering that the dev
profile is active, FooProperties.list
will contain one MyPojo
entry (with name “my another name” and description null).
在上面的例子中,假设dev
profile被激活,FooProperties.list
将包含一个MyPojo
输入(name为“my another name”,description为空)。
24.7 Type-safe Configuration Properties
Using the @Value("${property}")
annotation to inject configuration properties can sometimes be cumbersome, especially if you are working with multiple properties or your data is hierarchical in nature. Spring Boot provides an alternative method of working with properties that allows strongly typed beans to govern and validate the configuration of your application. For example:
使用@Value("${property}")
注解来注入配置信息有时会很麻烦,尤其是你正在使用多属性或你的数据本质上是分层的情况下。Spring Boot提供了一种处理属性的可替代方法,允许强类型的beans管理和验证你的应用的配置。例如:
1 | "connection") (prefix= |
The getters and setters are advisable, since binding is via standard Java Beans property descriptors, just like in Spring MVC. They are mandatory for immutable types or those that are directly coercible from
String
. As long as they are initialized, maps, collections, and arrays need a getter but not necessarily a setter since they can be mutated by the binder. If there is a setter, Maps, collections, and arrays can be created. Maps and collections can be expanded with only a getter, whereas arrays require a setter. Nested POJO properties can also be created (so a setter is not mandatory) if they have a default constructor, or a constructor accepting a single value that can be coerced fromString
. Some people use Project Lombok to add getters and setters automatically.
建议添加getters和setters,绑定是通过标准的Java Beans属性描述符,像在Spring MVC中一样。对于不可变类型或那些从
String
中可直接强制转换的类型,它们是强制性的。只要它们被初始化,maps,集合或数组需要getter方法,但不需要setter方法因为通过绑定起它们可以直接变化。如果有setter,可以创建Maps,集合和数组。Maps和集合可以通过getter扩展,数组扩展需要setter。如果它们有默认的构造函数,或构造函数接收可以从String
类型强制转换的值,嵌入的POJO属性也可以创建(因此setter不是强制性的)。一些人使用Lombok项目来自动添加getter和setter。See also the differences between
@Value
and@ConfigurationProperties
.
请看
@Value
和@ConfigurationProperties
之间的不同。
You also need to list the properties classes to register in the @EnableConfigurationProperties
annotation:
你也需要在@EnableConfigurationProperties
注解中列出要注册的属性类:
1 |
|
When
@ConfigurationProperties
bean is registered that way, the bean will have a conventional name:<prefix>-<fqn>
, where<prefix>
is the environment key prefix specified in the@ConfigurationProperties
annotation and<fqn>
the fully qualified name of the bean. If the annotation does not provide any prefix, only the fully qualified name of the bean is used.The bean name in the example above will be
connection-com.example.ConnectionProperties
, assuming thatConnectionProperties
sits in thecom.example
package.
当
@ConfigurationProperties
以那种方式注册时,这个bean将有一个常规的名字:<prefix>-<fqn>
,<prefix>
是在@ConfigurationProperties
注解中指定的环境关键字的前缀,<fqn>
是bean的完整合格的名字。如果注解没有提供任何前缀,则只用bean的完整合格的名字。在上面的例子中bean名字是
connection-com.example.ConnectionProperties
,假设ConnectionProperties
在com.example
包中。
Even if the configuration above will create a regular bean for ConnectionProperties
, we recommend that @ConfigurationProperties
only deal with the environment and in particular does not inject other beans from the context. Having said that, The @EnableConfigurationProperties
annotation is also automatically applied to your project so that any existing bean annotated with @ConfigurationProperties
will be configured from the Environment
properties. You could shortcut MyConfiguration
above by making sure ConnectionProperties
is a already a bean:
即使上面的配置会为ConnectionProperties
创建一个正规的bean,我们建议@ConfigurationProperties
只处理环境,特别是不从上下文中注入其它的beans。已经说过,为了任何带有@ConfigurationProperties
注解的bean可以根据Environment
属性进行配置,@EnableConfigurationProperties
注解也自动应用到你的工程中。确保ConnectionProperties
已经是一个bean,你可以简写上面的MyConfiguration
:
1 |
|
This style of configuration works particularly well with the SpringApplication
external YAML configuration:
这种风格的配置在SpringApplication
的外部化YAML配置中工作的尤其好:
1 | # application.yml |
To work with @ConfigurationProperties
beans you can just inject them in the same way as any other bean.
为了同@ConfigurationProperties
beans一起工作,你可以像任何其它bean一样以相同的方式注入它们:
1 | @Service |
Using
@ConfigurationProperties
also allows you to generate meta-data files that can be used by IDEs. See the Appendix B, Configuration meta-data appendix for details.
使用
@ConfigurationProperties
也允许你生成IDEs可以使用的元数据文件。更多细节请看附录B,配置元数据附录。
24.7.1 Third-party configuration
As well as using @ConfigurationProperties
to annotate a class, you can also use it on public @Bean
methods. This can be particularly useful when you want to bind properties to third-party components that are outside of your control.
To configure a bean from the Environment properties, add @ConfigurationProperties to its bean registration:
也可以使用@ConfigurationProperties
来注解一个类,你也可以在公有的@Bean
方法上使用它。当你想绑定属性到你控制之外的第三方组件上时尤其有用。
1 | @ConfigurationProperties(prefix = "foo") |
Any property defined with the foo
prefix will be mapped onto that FooComponent
bean in a similar manner as the ConnectionProperties
example above.
任何定义的带有foo
前缀的属性都将以类似于上面的ConnectionProperties
例子中的方式映射到FooComponent
bean中。
24.7.2 Relaxed binding
Spring Boot uses some relaxed rules for binding Environment
properties to @ConfigurationProperties
beans, so there doesn’t need to be an exact match between the Environment
property name and the bean property name. Common examples where this is useful include dashed separated (e.g. context-path
binds to contextPath
), and capitalized (e.g. PORT
binds to port
) environment properties.
Spring Boot使用一些松散的规则将Environment
属性绑定到@ConfigurationProperties
beans上,因此不需要在Environment
属性名和bean属性名之间进行确切的匹配。常见的有用例子包括破折号分隔(例如,context-path绑定到contextPath),大小写(例如PORT
绑定到port
,)环境属性。
For example, given the following @ConfigurationProperties
class:
例如,给定下面的@ConfigurationProperties
类:
1 | @ConfigurationProperties(prefix="person") |
The following properties names can all be used:
下面的属性名都可以使用:
Table 24.1. relaxed binding
Property | Note |
---|---|
person.firstName | Standard camel case syntax. |
person.first-name | Dashed notation, recommended for use in .properties and .yml files. |
person.first_name | Underscore notation, alternative format for use in .properties and .yml files. |
PERSON_FIRST_NAME | Upper case format. Recommended when using a system environment variables. |
表24.1. 松散绑定
Property | Note |
---|---|
person.firstName | 标准的驼峰写法 |
person.first-name | 破折号注解,建议在.properties 和.yml 文件中使用 |
person.first_name | 下划线注解,.properties 和.yml 文件中的可替代写法 |
PERSON_FIRST_NAME | 大写形式。当使用系统变量时推荐 |
24.7.3 Properties conversion
Spring will attempt to coerce the external application properties to the right type when it binds to the @ConfigurationProperties
beans. If you need custom type conversion you can provide a ConversionService
bean (with bean id conversionService) or custom property editors (via a CustomEditorConfigurer
bean) or custom Converters
(with bean definitions annotated as @ConfigurationPropertiesBinding
).
当Spring绑定属性到@ConfigurationProperties
beans时,它将试图将外部的应用属性强制转换成正确的类型。如果你需要定制类型转换你可以提供一个ConversionService
bean(bean id为conversionService
),或定制属性编辑器(通过CustomEditorConfigurer
bean),或定制Converters
(带有@ConfigurationPropertiesBinding
注解的bean定义)。
As this bean is requested very early during the application lifecycle, make sure to limit the dependencies that your
ConversionService
is using. Typically, any dependency that you require may not be fully initialized at creation time. You may want to rename your customConversionService
if it’s not required for configuration keys coercion and only rely on custom converters qualified with@ConfigurationPropertiesBindings
.
bean要求在应用生命周期中的早期,要确保限制
ConversionService
使用的依赖。通常,任何你要求的依赖可能在创建时不是完整初始化的。如果你定制的ConversionService
不要求配置关键字强制转换,你可能想重新命名你定制的ConversionService
,并且只依赖满足@ConfigurationPropertiesBindings
的定制转换器。
24.7.4 @ConfigurationProperties Validation
Spring Boot will attempt to validate external configuration, by default using JSR-303 (if it is on the classpath). You can simply add JSR-303 javax.validation
constraint annotations to your @ConfigurationProperties
class:
Spring Boot会试图验证外部化配置,默认使用JSR-303(如果它在classpath中)。你可以简单的添加JSR-303 javax.validation
约束注解到你的@ConfigurationProperties
类中:
1 | @ConfigurationProperties(prefix="connection") |
In order to validate values of nested properties, you must annotate the associated field as @Valid
to trigger its validation. For example, building upon the above ConnectionProperties
example:
为了验证嵌入的属性值,你必须注解相关的字段作为@Valid
来触发它的校验。例如,在上面的ConnectionProperties
例子上构建:
1 | @ConfigurationProperties(prefix="connection") |
You can also add a custom Spring Validator
by creating a bean definition called configurationPropertiesValidator
. The @Bean
method should be declared static. The configuration properties validator is created very early in the application’s lifecycle and declaring the @Bean
method as static allows the bean to be created without having to instantiate the @Configuration
class. This avoids any problems that may be caused by early instantiation. There is a property validation sample so you can see how to set things up.
通过创建一个称为configurationPropertiesValidator
的bean定义,你也可以添加定制的Spring Validator
。@Bean
方法应该声明静态的。配置属性验证器在应用生命周期的早期创建,声明@Bean
方法为静态方法,允许不必实例化@Configuration
类就创建bean。这避免了任何早期实例化可能引起的问题。这儿有一个属性验证的例子因此你可以看一下怎样设置它。
The
spring-boot-actuator
module includes an endpoint that exposes all@ConfigurationProperties
beans. Simply point your web browser to/configprops
or use the equivalent JMX endpoint. See the Production ready features. section for details.
spring-boot-actuator
模块包含一个端点,这个端点将公开所有的@ConfigurationProperties
beans。简单的将你的web浏览器指向/configprops
或用等价的JMX端点。更多细节请看产品级功能。
24.7.5 @ConfigurationProperties vs. @Value
@Value
is a core container feature and it does not provide the same features as type-safe Configuration Properties. The table below summarizes the features that are supported by @ConfigurationProperties
and @Value
:
@Value
是一种核心的容器功能,它不能作为类型安全配置属性提供同样的功能。下面的表中总结了@ConfigurationProperties
和@Value
支持的功能:
Feature | @ConfigurationProperties |
@Value |
---|---|---|
Relaxed binding | Yes | No |
Meta-data support | Yes | No |
SpEL evaluation | No | Yes |
功能 | @ConfigurationProperties |
@Value |
---|---|---|
松散绑定 | Yes | No |
元数据支持 | Yes | No |
SpEL评估 | No | Yes |
If you define a set of configuration keys for your own components, we recommend you to group them in a POJO annotated with @ConfigurationProperties
. Please also be aware that since @Value
does not support relaxed binding, it isn’t a great candidate if you need to provide the value using environment variables.
如果你为自己的组件定义了一些配置关键字,我们建议你将它们分组到带有@ConfigurationProperties
注解的POJO中。也请注意@Value
不支持松散绑定,如果你需要用环境变量提供值,它不是一个好的选择。
Finally, while you can write a SpEL expression in @Value
, such expressions are not processed from Application property files.
最后,虽然你可以在@Value
中写表达式,但这种表达式不能从应用属性文件中处理。
25. Profiles
Spring Profiles provide a way to segregate parts of your application configuration and make it only available in certain environments. Any @Component
or @Configuration
can be marked with @Profile
to limit when it is loaded:
Spring Profiles提供了一种隔离部分应用配置的方式,并让这些配置只在特定的环境生效。任何带有@Profile
标记的@Component
或@Configuration
在加载时都会受限制:
1 | @Configuration |
In the normal Spring way, you can use a spring.profiles.active
Environment
property to specify which profiles are active. You can specify the property in any of the usual ways, for example you could include it in your application.properties
:
以正常的Spring方式,你可以使用spring.profiles.active
Environment
属性来指定激活哪一个profiles。你可以在任何常见的方式指定这个属性,例如你可以在你的application.properties
中包含它:
1 | spring.profiles.active=dev,hsqldb |
or specify on the command line using the switch --spring.profiles.active=dev,hsqldb
.
或在命令行用--spring.profiles.active=dev,hsqldb
转换。
25.1 Adding active profiles
The spring.profiles.active
property follows the same ordering rules as other properties, the highest PropertySource
will win. This means that you can specify active profiles in application.properties
then replace them using the command line switch.
spring.profiles.active
属性与其它的属性一样遵循同样的排序规则,最高的PropertySource
优先。这意味着你可以在application.properties
指定激活的profiles,然后用命令行转换替代它们。
Sometimes it is useful to have profile-specific properties that add to the active profiles rather than replace them. The spring.profiles.include
property can be used to unconditionally add active profiles. The SpringApplication
entry point also has a Java API for setting additional profiles (i.e. on top of those activated by the spring.profiles.active
property): see the setAdditionalProfiles()
method.
有时通过特定的profile属性添加激活的profiles而不替换它们是很有用的。spring.profiles.include
属性可以用来无条件添加激活的profiles。SpringApplication
入口也有设置额外的profiles的Java API(例如上面的通过spring.profiles.active
属性激活的profiles):请看setAdditionalProfiles()
方法。
For example, when an application with following properties is run using the switch --spring.profiles.active=prod
the proddb
and prodmq
profiles will also be activated:
例如,当一个应用具有以下属性且运行时使用--spring.profiles.active=prod
转换,proddb
和prodmq
profiles也将被激活:
1 | --- |
Remember that the
spring.profiles
property can be defined in a YAML document to determine when this particular document is included in the configuration. See Section 70.7, “Change configuration depending on the environment” for more details.
记住可以在YAML文档中定义
spring.profiles
来决定在配置中包含特定的文档。更多细节请看70.7小节,“根据环境更改配置”。
25.2 Programmatically setting profiles
You can programmatically set active profiles by calling SpringApplication.setAdditionalProfiles(…)
before your application runs. It is also possible to activate profiles using Spring’s ConfigurableEnvironment
interface.
你可以在你的应用运行之前以编程的方式调用SpringApplication.setAdditionalProfiles(…)
来设置激活的profiles。也可以使用Spring的ConfigurableEnvironment
接口来激活profiles。
25.3 Profile-specific configuration files
Profile-specific variants of both application.properties
(or application.yml
) and files referenced via @ConfigurationProperties
are considered as files are loaded. See Section 24.4, “Profile-specific properties” for details.
application.properties
(或application.yml
)和通过@ConfigurationProperties
引用的文件的特定profiles变种都被当做文件进行加载。更多细节请看24.4小节,“Profile-specific properties”。
26. Logging
Spring Boot uses Commons Logging for all internal logging, but leaves the underlying log implementation open. Default configurations are provided for Java Util Logging, Log4J2 and Logback. In each case loggers are pre-configured to use console output with optional file output also available.
Spring Boot所有的内部日志都采用Commons Logging,但开放了底层的日志实现。提供了对Java Util Logging,Log4J2和Logback的默认实现。在每个logger中都预先配置使用控制台作为输出,同时也可用可选的文件输出。
By default, If you use the ‘Starters’, Logback will be used for logging. Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J or SLF4J will all work correctly.
默认情况下,如果使用Starters
,Logback将作为日志。也要包含恰当的Logback规则来保证依赖库使用Java Util Logging,Commons Logging,Log4J或SLF4J都能正确工作。
There are a lot of logging frameworks available for Java. Don’t worry if the above list seems confusing. Generally you won’t need to change your logging dependencies and the Spring Boot defaults will work just fine.
在Java中有许多日志框架可用。不必担心上面的列表看起来有点混乱。通常情况下你不需要改变你的日志依赖,Spring Boot默认情况下能很好的工作。
26.1 Log format
The default log output from Spring Boot looks like this:
Spring Boot默认的日志输出看起来如下:
1 | 2014-03-05 10:57:51.112 INFO 45469 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomcat/7.0.52 |
The following items are output:
Date and Time — Millisecond precision and easily sortable.
Log Level — ERROR, WARN, INFO, DEBUG or TRACE.
Process ID.
A
---
separator to distinguish the start of actual log messages.Thread name — Enclosed in square brackets (may be truncated for console output).
Logger name — This is usually the source class name (often abbreviated).
The log message.
下面的是输出项:
Date and Time — 精确到毫秒且容易排序。
Log级别 — ERROR,WARN,INFO,DEBUG或TRACE。
进程ID。
---
分隔符来区分真正的日志信息的开始。线程名称 — 用方括号包裹(在控制台输出中经常是缩减的)。
Logger名称 — 源类名(经常是简写)。
日志信息。
Logback does not have a FATAL level (it is mapped to ERROR)
Logback没有FATAL级别(它映射到ERROR)。
26.2 Console output
The default log configuration will echo messages to the console as they are written. By default ERROR
, WARN
and INFO
level messages are logged. You can also enable a “debug” mode by starting your application with a --debug
flag.
默认的日志配置会将信息输出到控制台。默认情况下会输出ERROR
,WARN
和INFO
级别的信息。你也可以通过--debug
来启动你的应用,从而启用“debug”模式。
1 | $ java -jar myapp.jar --debug |
you can also specify
debug=true
in yourapplication.properties
.
你也可以在
application.properties
指定debug=true
。
When the debug mode is enabled, a selection of core loggers (embedded container, Hibernate and Spring Boot) are configured to output more information. Enabling the debug mode does not configure your application to log all messages with DEBUG
level.
当启用调试模式时,配置选择的核心logger(嵌入式容器,Hibernate和Spring Boot)来输出更多的信息。启动调试模式不会将你的应用配置成输出所有DEBUG
级别的信息。
Alternatively, you can enable a “trace” mode by starting your application with a --trace
flag (or trace=true
in your application.properties
). This will enable trace logging for a selection of core loggers (embedded container, Hibernate schema generation and the whole Spring portfolio).
或者,你可以用--trace
标记(或在application.properties
中添加trace=true
)启动你的应用,从而启用“trace”模式。这将在选择的核心logger中(嵌入式容器,Hibernate模式生成和整个Spring文件夹)启用trace日志。
26.2.1 Color-coded output
If your terminal supports ANSI, color output will be used to aid readability. You can set spring.output.ansi.enabled
to a supported value to override the auto detection.
如果你的终端支持ANSI,颜色输出可以用来辅助阅读。你可以为spring.output.ansi.enabled
设置一个支持值来覆盖自动检测。
Color coding is configured using the %clr
conversion word. In its simplest form the converter will color the output according to the log level, for example:
颜色编码用%clr
转换词来配置。最简单的形式是根据日志级别进行颜色输出,例如:
1 | %clr(%5p) |
The mapping of log level to a color is as follows:
日志级别与颜色的映射如下:
Level | Color |
---|---|
FATAL | Red |
ERROR | Red |
WARN | Yellow |
INFO | Green |
DEBUG | Green |
TRACE | Green |
Alternatively, you can specify the color or style that should be used by providing it as an option to the conversion. For example, to make the text yellow:
或者,你可以通过在转换器中提供选项来指定应该试用的颜色或风格。例如,为了使文本显示黄色:
1 | %clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow} |
The following colors and styles are supported:
支持下面的颜色和风格:
- blue
- cyan
- faint
- green
- magenta
- red
- yellow
26.3 File output
By default, Spring Boot will only log to the console and will not write log files. If you want to write log files in addition to the console output you need to set a logging.file
or logging.path
property (for example in your application.properties
).
默认情况下,Spring Boot只能输出日志到控制台,不会写入日志文件。如果你想除了控制台之外还想写日志文件,你需要设置logging.file
或logging.path
属性(例如,在你的application.properties
)。
The following table shows how the logging.*
properties can be used together:
下表显示了logging.*
属性怎样在一起使用:
Table 26.1. Logging properties
logging.file | logging.path | Example | Description |
---|---|---|---|
(none | (none) | Console only logging. | |
Specific file | (none) | my.log | Writes to the specified log file. Names can be an exact location or relative to the current directory. |
(none) | Specific directory | /var/log | Writes spring.log to the specified directory. Names can be an exact location or relative to the current directory. |
表 26.1. Logging属性
logging.file | logging.path | Example | Description |
---|---|---|---|
(none | (none) | 只输出到控制台 | |
指定文件 | (none) | my.log | 写入指定的日志文件。名字可以是一个绝对位置或相对于当前目录。 |
(none) | Specific directory | /var/log | 写spring.log 到一个指定的目录。名字可以是一个绝对位置或相对于当前目录。 |
Log files will rotate when they reach 10 MB and as with console output, ERROR
, WARN
and INFO
level messages are logged by default.
当日志文件达到10M时日志文件将循环,至于控制台输出,默认情况下只输出ERROR
,WARN
和INFO
级别的信息。
The logging system is initialized early in the application lifecycle and as such logging properties will not be found in property files loaded via
@PropertySource
annotations.
日志系统在应用程序的生命周期早期进行初始化,同样地,通过
@PropertySource
注解加载的属性文件中将不会发现日志属性。
Logging properties are independent of the actual logging infrastructure. As a result, specific configuration keys (such as
logback.configurationFile
for Logback) are not managed by spring Boot.
日志属性独立于真正的日志基础架构之外。因此,Spring Boot不管理特定的配置主键(例如Logback的
logback.configurationFile
)。
26.4 Log Levels
All the supported logging systems can have the logger levels set in the Spring Environment
(so for example in application.properties
) using ‘logging.level.*=LEVEL’ where ‘LEVEL’ is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF. The root
logger can be configured using logging.level.root
. Example application.properties
:
Spring支持的所有日志系统都可以在Spring的Environment
中设置日志级别(例如在application.properties
设置),使用logging.level.*=LEVEL
进行设置,LEVEL
是TRACE,DEBUG,INFO,WARN,ERROR,FATAL,OFF中的一个。root
日志器可以用logging.level.root
来配置。例如在application.properties
中:
1 | logging.level.root=WARN |
By default Spring Boot remaps Thymeleaf
INFO
messages so that they are logged atDEBUG
level. This helps to reduce noise in the standard log output. SeeLevelRemappingAppender
for details of how you can apply remapping in your own configuration.
默认情况下Spring Boot重新映射Thymeleaf的
INFO
信息,为了它们能在DEBUG
级别进行输出。这能帮助减少标准日志输出中的噪声。关于怎样在你自己的配置中使用重新映射的更多细节请看LevelRemappingAppender
。
26.5 Custom log configuration
The various logging systems can be activated by including the appropriate libraries on the classpath, and further customized by providing a suitable configuration file in the root of the classpath, or in a location specified by the Spring Environment
property logging.config
.
在类路径中通过包含恰当的库可以激活各种日志系统,在类路径的根目录中提供一个合适的配置文件可以对日志系统进行更进一步的定制,或者将配置文件放在Spring Environment
的logging.config
属性中指定的位置。
You can force Spring Boot to use a particular logging system using the org.springframework.boot.logging.LoggingSystem
system property. The value should be the fully-qualified class name of a LoggingSystem
implementation. You can also disable Spring Boot’s logging configuration entirely by using a value of none
.
你可以使用系统属性org.springframework.boot.logging.LoggingSystem
来强制Spring Boot使用一个特定的日志系统。它的值应该是全限定类名的LoggingSystem
实现。你也可以通过使用值none
来完全禁用Spring Boot的日志配置。
Since logging is initialized before the
ApplicationContext
is created, it isn’t possible to control logging from@PropertySources
in Spring@Configuration
files. System properties and the conventional Spring Boot external configuration files work just fine.
由于日志是在
ApplicationContext
创建之前初始化,因此不可能从Spring@Configuration
文件中的@PropertySources
来控制日志。系统属性和传统的Spring Boot外部配置文件可以工作的很好。
Depending on your logging system, the following files will be loaded:
根据你的日志系统,将会加载下面的文件:
Logging System | Customization |
---|---|
Logback | logback-spring.xml, logback-spring.groovy, logback.xml or logback.groovy |
Log4j2 | log4j2-spring.xml or log4j2.xml |
JDK (Java Util Logging) | logging.properties |
When possible we recommend that you use the
-spring
variants for your logging configuration (for examplelogback-spring.xml
rather thanlogback.xml
). If you use standard configuration locations, Spring cannot completely control log initialization.
我们建议你尽可能的使用
-spring
变种来进行日志配置(例如,logback-spring.xml
而不是logback.xml
)。如果你在使用标准的配置路径,Spring不能完全控制日志的初始化。
There are known classloading issues with Java Util Logging that cause problems when running from an ‘executable jar’. We recommend that you avoid it if at all possible.
在Java Java Util Logging中存在类加载问题,当从
executable jar
运行时会引起问题。我们建议你尽可能的避免它。
To help with the customization some other properties are transferred from the Spring Environment
to System properties:
为了帮助定制一些其它属性,从Spring Environment
中转移到系统属性中:
Spring Environment | System Property | Comments |
---|---|---|
logging.exception-conversion-word | LOG_EXCEPTION_CONVERSION_WORD | The conversion word that’s used when logging exceptions. |
logging.file | LOG_FILE | Used in default log configuration if defined. |
logging.path | LOG_PATH | Used in default log configuration if defined. |
logging.pattern.console | CONSOLE_LOG_PATTERN | The log pattern to use on the console (stdout). (Only supported with the default logback setup.) |
logging.pattern.file | FILE_LOG_PATTERN | The log pattern to use in a file (if LOG_FILE enabled). (Only supported with the default logback setup.) |
logging.pattern.level | LOG_LEVEL_PATTERN | The format to use to render the log level (default %5p). (Only supported with the default logback setup.) |
PID | PID | The current process ID (discovered if possible and when not already defined as an OS environment variable). |
Spring Environment | System Property | Comments |
---|---|---|
logging.exception-conversion-word | LOG_EXCEPTION_CONVERSION_WORD | 当日志出现异常时会用到这个转换词。 |
logging.file | LOG_FILE | 如果定义了,会在默认的日志配置中使用。 |
logging.path | LOG_PATH | 如果定义了,会在默认的日志配置中使用。 |
logging.pattern.console | CONSOLE_LOG_PATTERN | 用在控制台中的日志模式(stdout)。(只支持默认的Logback设置。) |
logging.pattern.file | FILE_LOG_PATTERN | 用在文件中的日志模式 (如果启用LOG_FILE )。(只支持默认的Logback设置。) |
logging.pattern.level | LOG_LEVEL_PATTERN | 这种模式用来实施日志级别(默认%5p )。 (只支持默认的Logback设置。) |
PID | PID | 当前的进程ID |
All the logging systems supported can consult System properties when parsing their configuration files. See the default configurations in spring-boot.jar
for examples.
当转换配置文件时,所有的日志系统都支持查询系统属性。例如spring-boot.jar
的默认配置。
If you want to use a placeholder in a logging property, you should use Spring Boot’s syntax and not the syntax of the underlying framework. Notably, if you’re using Logback, you should use
:
as the delimiter between a property name and its default value and not:-
.
如果你在日志属性中想使用占位符,你应该试用Spring Boot的语法而不是底层框架的语法。尤其是,如果你在使用Logback,你应该使用
:
作为属性名和默认值之间的分隔符,而不是:-
。
You can add MDC and other ad-hoc content to log lines by overriding only the
LOG_LEVEL_PATTERN
(orlogging.pattern.level
with Logback). For example, if you uselogging.pattern.level=user:%X{user} %5p
then the default log format will contain an MDC entry for “user” if it exists, e.g.
1
2 2015-09-30 12:30:04.031 user:juergen INFO 22174 --- [ nio-8080-exec-0] demo.Controller
Handling authenticated request
你可以通过重写
LOG_LEVEL_PATTERN
(或Logback中的logging.pattern.level
)来添加MDC和其它的专门内容来日志行中。例如,你可以使用logging.pattern.level=user:%X{user} %5p
,默认的日志形式将包含MDC输入,如果它存在的话,例如:
1
2 2015-09-30 12:30:04.031 user:juergen INFO 22174 --- [ nio-8080-exec-0] demo.Controller
Handling authenticated request
26.6 Logback extensions
Spring Boot includes a number of extensions to Logback which can help with advanced configuration. You can use these extensions in your logback-spring.xml
configuration file.
Spring Boot包含许多Logback的扩展,这有助于进行更高级的配置。你可以在你的logback-spring.xml
配置文件中使用这些扩展。
You cannot use extensions in the standard
logback.xml
configuration file since it’s loaded too early. You need to either uselogback-spring.xml
or define alogging.config
property.
你不能在标准的
logback.xml
配置文件中使用扩展,因为它加载的太早了。你需要使用logback-spring.xml
或定义logging.config
属性。
26.6.1 Profile-specific configuration
The <springProfile>
tag allows you to optionally include or exclude sections of configuration based on the active Spring profiles. Profile sections are supported anywhere within the <configuration>
element. Use the name
attribute to specify which profile accepts the configuration. Multiple profiles can be specified using a comma-separated list.
<springProfile>
标签允许你自由的包含或排除基于激活的Spring profiles的配置的一部分。在<configuration>
元素的任何地方都支持Profile部分。使用name
属性来指定哪一个profile接受配置。多个profiles可以用一个逗号分隔的列表来指定。
1 | <springProfile name="staging"> |
26.6.2 Environment properties
The <springProperty>
tag allows you to surface properties from the Spring Environment
for use within Logback. This can be useful if you want to access values from your application.properties
file in your logback configuration. The tag works in a similar way to Logback’s standard <property>
tag, but rather than specifying a direct value
you specify the source
of the property (from the Environment
). You can use the scope
attribute if you need to store the property somewhere other than in local
scope. If you need a fallback value in case the property is not set in the Environment
, you can use the defaultValue
attribute.
<springProperty>
标签允许你在Logback使用从Spring Environment
获得的属性。如果你想在你的Logback配置中访问application.properties
文件中的属性,这是非常有用的。这个标签与Logback的标准<property>
标签的作用方式类似,但不是为你指定的source
属性(从Environment
中)指定一个直接的value
。如果你需要在某个地方而不是在local
作用域中存储属性,你可以使用scope
属性。如果你需要一个备用值以防属性没有在Environment
中设置,你可以使用defaultValue
属性。
1 | <springProperty scope="context" name="fluentHost" source="myapp.fluentd.host" |
The
RelaxedPropertyResolver
is used to accessEnvironment
properties. If specify thesource
in dashed notation (my-property-name
) all the relaxed variations will be tried (myPropertyName
,MY_PROPERTY_NAME
etc).
RelaxedPropertyResolver
是用来访问Environment
属性。如果在破折号符号中指定了source
,则会尝试所有的不严格的变种(myPropertyName
,MY_PROPERTY_NAME
等)。